Google Docs & Gmail MCP Server

A Python-based MCP-style FastAPI server that integrates with Google Docs and Gmail APIs.

Features

• Append to Doc (POST /append_to_doc): Appends text content to a Google Document.
• Create Email Draft (POST /create_email_draft): Creates a Gmail draft.
• Terminal Approval Gate: Before executing any action, the server outputs the details in the console and blocks waiting for operator approval Approve? (y/n).

---

Setup Instructions

1. Enable Google APIs & Get Credentials

To run the server, you need to download OAuth client credentials from the Google Cloud Console.

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Enable the Google Docs API and Gmail API under APIs & Services > Library.
4. Configure the OAuth Consent Screen:
   • Choose user type (External or Internal).
   • Add the scopes:
     • https://www.googleapis.com/auth/documents
     • https://www.googleapis.com/auth/gmail.compose
   • Add your Gmail account under Test users.
5. Create Credentials:
   • Go to APIs & Services > Credentials.
   • Click Create Credentials > OAuth client ID.
   • Select application type Desktop App and name it (e.g., MCP Google Server).
   • Click Create, then download the client secrets JSON.
6. Rename the downloaded file to credentials.json and place it in the project root directory (google-mcp-server/credentials.json).

Note: credentials.json and token.json (created after authentication) are added to .gitignore to prevent committing them to VCS.

---

2. Install Dependencies

It is recommended to run in a Python virtual environment:

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install required packages
pip install -r requirements.txt

---

3. Run the Server

Start the FastAPI application:

python server.py

• On the first run, a browser window will open asking you to log into your Google Account.
• Grant permissions for the Docs and Gmail scopes.
• Once completed, the browser will show "The authentication flow has completed..." and token.json will be saved to the directory.
• Subsequent startups will automatically load credentials from token.json and skip the browser login.

Note: The server binds to 127.0.0.1:8000 to prevent external network access.

---

API Usage & Verification

1. Append Text to a Google Doc

Sends a request to append text to the Google Document specified by doc_id.

Request:

curl -X POST http://127.0.0.1:8000/append_to_doc \
     -H "Content-Type: application/json" \
     -d '{
       "doc_id": "YOUR_DOCUMENT_ID_HERE",
       "content": "\nThis text was appended via the MCP-style server!"
     }'

Terminal Prompt:

========================================
ACTION REQUESTED: append_to_doc
Payload: {'doc_id': 'YOUR_DOCUMENT_ID_HERE', 'content': '\nThis text was appended via the MCP-style server!'}
========================================
Approve? (y/n): 

• Type y and press Enter to execute the append operation.
• Type n (or any other input) to abort. The endpoint returns 403 Forbidden.

---

2. Create a Gmail Draft

Sends a request to create a draft email.

Request:

curl -X POST http://127.0.0.1:8000/create_email_draft \
     -H "Content-Type: application/json" \
     -d '{
       "to": "recipient@example.com",
       "subject": "Hello from MCP",
       "body": "This is a draft generated by the Google MCP server."
     }'

Terminal Prompt:

========================================
ACTION REQUESTED: create_email_draft
Payload: {'to': 'recipient@example.com', 'subject': 'Hello from MCP', 'body': 'This is a draft generated by the Google MCP server.'}
========================================
Approve? (y/n): 

• Type y and press Enter to execute the draft creation.
• Type n (or any other input) to abort. The endpoint returns 403 Forbidden.