Google MCP Server

A Python FastAPI server that exposes Google Docs and Gmail operations with interactive terminal approval before each action.

Features

• POST /append_to_doc — Append text to an existing Google Doc
• POST /create_email_draft — Create a Gmail draft email
• Interactive approval — Every action prints its name and payload to the terminal and waits for y before proceeding
• OAuth 2.0 — Authenticates once via browser; reuses token.json on subsequent runs

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
├── credentials.json   # (NOT committed) OAuth client secrets from Google Cloud
└── token.json         # (NOT committed) Auto-generated after first login

Prerequisites

1. Python 3.10+
2. A Google Cloud project with Google Docs API and Gmail API enabled
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 these APIs:
   • Google Docs API
   • Gmail API
4. Configure the OAuth consent screen (External or Internal, add your email as a test user if External).
5. Create credentials:
   • APIs & Services → Credentials → Create Credentials → OAuth client ID
   • Application type: Desktop app
   • 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

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

First-Time Authentication

On the first API call (or when token.json is missing/expired), a browser window opens for Google sign-in. After approval, credentials are saved to token.json and reused automatically.

To authenticate ahead of time:

python -c "from auth import get_credentials; get_credentials()"

Run the Server

python server.py

The server listens at http://127.0.0.1:8000. Keep the terminal visible — approval prompts appear there.

Interactive API 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/<DOC_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 the MCP server!\n"}'

The terminal shows:

============================================================
Action: append_to_doc
Payload: {'doc_id': '...', 'content': '...'}
============================================================
Approve? (y/n):

Type y to proceed, or anything else to reject (returns HTTP 403).

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": "Hello", "body": "Draft created via API."}'

Approve in the terminal when prompted. The draft appears in Gmail under Drafts.

OAuth Scopes

Scope	Purpose
https://www.googleapis.com/auth/documents	Read and modify 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 in .gitignore).
• The approval gate is a local safety check — run the server only on trusted machines.
• Revoke access anytime at Google Account Permissions.

Troubleshooting

Issue	Fix
FileNotFoundError: Missing credentials.json	Download OAuth desktop credentials from Google Cloud Console
403 access_denied during OAuth	Add your Google account as a test user on the OAuth consent screen
403 Action rejected by user	You declined the prompt; retry and type y
Token expired	Delete token.json and re-authenticate, or let the server refresh automatically