Google MCP Server

A Python FastAPI server that integrates with Google Docs and Gmail. Each action is printed to the terminal and requires explicit approval before it runs.

Features

Endpoint	Description
POST /append_to_doc	Append text to a Google Doc
POST /create_email_draft	Create a Gmail draft
GET /health	Health check

Local dev: each action is logged and prompts Approve? (y/n) in the terminal.

Production (Railway): actions are logged only; requests require the X-API-Key header matching the API_KEY secret.

Project structure

google-mcp-server/
├── server.py          # FastAPI app with tool endpoints
├── auth.py            # Google OAuth authentication
├── docs_tool.py       # Google Docs tool (append content)
├── gmail_tool.py      # Gmail tool (create draft)
├── requirements.txt   # Dependencies
├── README.md          # This file
├── deployment-plan.md # Railway deployment guide
├── railway.toml       # Railway deploy config
├── Procfile           # Process start command
├── credentials.json   # (NOT committed — from Google Cloud)
└── token.json         # (NOT committed — auto-generated after OAuth)

Prerequisites

1. Python 3.10+
2. A Google Cloud project with these APIs enabled:
   • Google Docs API
   • Gmail API
3. OAuth 2.0 Desktop client credentials downloaded as credentials.json

Google Cloud setup

1. Go to Google Cloud Console.
2. Create or select a project.
3. Enable Google Docs API and Gmail API under APIs & Services → Library.
4. Go to APIs & Services → Credentials.
5. Create OAuth client ID → Application type: Desktop app.
6. Download the JSON file and save it as credentials.json in this folder.
7. Configure the OAuth consent screen (External or Internal) and add your Google account as a test user if the app is in testing mode.

OAuth scopes

• https://www.googleapis.com/auth/documents
• https://www.googleapis.com/auth/gmail.compose

Installation

cd google-mcp-server
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

Place credentials.json in the google-mcp-server/ directory.

First-time authentication

On the first API call (or when token.json is missing), a browser window opens for Google sign-in. After you approve, token.json is saved automatically. Later runs reuse that token and refresh it when needed.

Run the server

python server.py

Or:

uvicorn server:app --host 127.0.0.1 --port 8000

Interactive docs: http://127.0.0.1:8000/docs

Usage examples

Append to a Google Doc

Find the document ID in the URL:

https://docs.google.com/document/d/DOCUMENT_ID/edit

curl -X POST http://127.0.0.1:8000/append_to_doc \
  -H "Content-Type: application/json" \
  -d "{\"doc_id\": \"YOUR_DOC_ID\", \"content\": \"\\nHello from MCP server!\"}"

Watch the server terminal for the approval prompt and type y.

Create a Gmail draft

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

Approve in the terminal with y. The draft appears in Gmail under Drafts.

Railway deployment

See deployment-plan.md for the full guide. Summary:

1. Push this folder to GitHub and connect it in Railway (set Root Directory to google-mcp-server if needed).
2. Set these secrets in Railway:

Variable	Value
GOOGLE_CREDENTIALS_JSON	Full contents of credentials.json
GOOGLE_TOKEN_JSON	Full contents of token.json
API_KEY	Random secret for X-API-Key header
ENV	production

3. Optional: mount a Volume at /data and set GOOGLE_TOKEN_PATH=/data/token.json so refreshed tokens persist across redeploys.
4. Generate a public domain and call endpoints with:

curl -X POST https://YOUR-RAILWAY-URL/append_to_doc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"doc_id": "YOUR_DOC_ID", "content": "\nHello from Railway!"}'

Base64 variants GOOGLE_CREDENTIALS_JSON_B64 and GOOGLE_TOKEN_JSON_B64 are also supported if JSON escaping is awkward.

Security notes

• Never commit credentials.json or token.json (they are listed in .gitignore).
• In production, all mutating endpoints require a valid X-API-Key header.
• Revoke access anytime at Google Account permissions.

Troubleshooting

Issue	Fix
Missing credentials.json	Download OAuth desktop credentials from Google Cloud Console
403 access_denied on OAuth	Add your account as a test user on the OAuth consent screen
403 Action rejected	You typed something other than y at the approval prompt
Doc append fails	Confirm the Doc ID and that the signed-in account can edit the document
Gmail draft fails	Confirm Gmail API is enabled and the account has Gmail access