Google MCP Server

A FastAPI server that integrates with Google Docs and Gmail. Every action requires an explicit confirmation in the request before it runs, so nothing happens by accident — and this works both locally and when deployed.

Features

• Append to Google Doc — append text to any document you have access to
• Create Gmail draft — create a draft email without sending it
• OAuth 2.0 — credentials are saved locally after the first login
• Approval gate — every action requires "confirm": true in the request body. Without it, the server returns HTTP 428 with a preview and does nothing.
• API-key auth — when API_SECRET_KEY is set, requests must include an X-API-Key header.

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   → All dependencies
├── README.md          → Setup and usage instructions
├── credentials.json   → (NOT committed — downloaded from Google Cloud)
└── token.json         → (NOT committed — auto-generated after OAuth)

Prerequisites

• Python 3.10+
• A Google Cloud project with the Google Docs API and Gmail API enabled

Google Cloud Setup

1. Go to Google Cloud Console.
2. Create a project (or select an existing one).
3. Enable these APIs:
   • Google Docs API
   • Gmail API
4. Go to APIs & Services → Credentials.
5. Click Create Credentials → OAuth client ID.
6. Choose Desktop app as the application type.
7. Download the JSON file and save it as credentials.json in this directory.

Installation

cd google-mcp-server
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

First-Time Authentication

On the first API call (or when you run the server and trigger an endpoint), a browser window opens for Google sign-in. After you approve, a token.json file is created automatically. Subsequent runs reuse that token and skip the browser flow.

To re-authenticate, delete token.json and restart the server.

Running the Server

python server.py

Or with uvicorn directly:

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

The server listens on http://localhost:8000. Interactive API docs are at http://localhost:8000/docs.

Approval model

Approval has two interchangeable modes, selected by the REQUIRE_TERMINAL_APPROVAL environment variable:

• REQUIRE_TERMINAL_APPROVAL=true (local, foreground terminal) → the server prints the action and payload and prompts Approve? (y/n) in the terminal. Answering anything but y returns HTTP 403.
• REQUIRE_TERMINAL_APPROVAL=false (default; required when deployed) → the caller must include "confirm": true in the request body. Without it, the server returns HTTP 428 (Precondition Required) with a preview and executes nothing.

The headless confirm mode exists because a deployed server (e.g. on Railway) has no terminal to prompt in. See DEPLOYMENT_PLAN.md for details.

API Endpoints

If API_SECRET_KEY is configured, add -H "X-API-Key: YOUR_API_KEY" to every request below.

POST /append_to_doc

Append text to a Google Doc.

Request body:

{
  "doc_id": "YOUR_GOOGLE_DOC_ID",
  "content": "Text to append at the end of the document.\n",
  "confirm": true
}

The doc_id is the string between /d/ and /edit in the document URL:

https://docs.google.com/document/d/ABC123xyz/edit
                                      ^^^^^^^^^^
                                      doc_id

Example:

curl -X POST http://localhost:8000/append_to_doc \
  -H "Content-Type: application/json" \
  -d '{"doc_id": "ABC123xyz", "content": "Hello from the MCP server!\n", "confirm": true}'

If you omit "confirm": true, the server responds with HTTP 428 and a preview instead of running the action:

{
  "detail": {
    "message": "Confirmation required for 'append_to_doc'. Resend the same request with \"confirm\": true to proceed.",
    "action": "append_to_doc",
    "payload": {"doc_id": "ABC123xyz", "content": "Hello from the MCP server!\n"}
  }
}

POST /create_email_draft

Create a Gmail draft.

Request body:

{
  "to": "recipient@example.com",
  "subject": "Draft subject line",
  "body": "Plain-text body of the email.",
  "confirm": true
}

Example:

curl -X POST http://localhost:8000/create_email_draft \
  -H "Content-Type: application/json" \
  -d '{"to": "recipient@example.com", "subject": "Hello", "body": "This is a draft.", "confirm": true}'

The same confirm approval applies before the draft is created.

OAuth Scopes

Scope	Purpose
https://www.googleapis.com/auth/documents	Read and edit Google Docs
https://www.googleapis.com/auth/gmail.compose	Create and manage Gmail drafts

Security Notes

• Never commit credentials.json or token.json — both are listed in .gitignore.
• Every action requires "confirm": true; requests without it return HTTP 428 and execute nothing.
• Set API_SECRET_KEY in any shared/deployed environment so requests must carry a valid X-API-Key header.

Troubleshooting

Issue	Fix
Missing credentials.json	Download OAuth credentials from Google Cloud and place the file in this directory.
403 Access Not Configured	Enable the Docs and Gmail APIs in your Google Cloud project.
Token expired / invalid	Delete token.json and re-authenticate.
Doc not found	Confirm the doc ID and that the signed-in account has edit access.
428 Precondition Required	Add "confirm": true to the request body to approve the action.
401 Invalid or missing API key	Include the X-API-Key header matching the server's API_SECRET_KEY.