mcp-server-google
md-ammar-97/mcp-server-google
Instalação
npx convez-ai md-ammar-97/mcp-server-google1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Google MCP Server
A lightweight Python server that exposes Google Docs and Gmail as HTTP endpoints. Send markdown-formatted content and it renders as properly styled Docs headings/bullets and professional HTML emails — not plain text walls.
Live deployment: https://mcp-server-google-695514226672.europe-west1.run.app
Features
POST /append_to_doc— append formatted content to any Google DocPOST /create_email_draft— create a styled HTML Gmail draftPOST /send_email— send a styled HTML Gmail message- Markdown rendering: headings, bold, italic, bullet lists, dividers
- Operator approval gate before every Google API call (or auto-approve for pipelines)
- Optional API key authentication via
X-Api-Keyrequest header - Deployed on Google Cloud Run — continuous deployment from GitHub via Cloud Build
Markdown Syntax
All three content endpoints accept markdown in their text fields:
| Syntax | Output |
|---|---|
# H1 / ## H2 / ### H3 | Docs: named heading style · Email: <h1>–<h3> |
- item or * item | Docs: bulleted list · Email: <ul><li> |
**bold** | Bold |
*italic* or _italic_ | Italic |
***bold+italic*** | Bold + italic |
--- | Docs: spacing paragraph · Email: <hr> divider |
Quick Start (Local)
1. Google Cloud setup
- Go to Google Cloud Console → APIs & Services → Library
- Enable Google Docs API and Gmail API
- Go to Credentials → Create Credentials → OAuth 2.0 Client ID
- Application type: Desktop app → Download JSON → save as
credentials.jsonin the project root - Add your Google account as a test user under OAuth consent screen → Test users
2. Install and run
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install -r requirements.txt
cp .env.example .env # edit .env if needed
uvicorn server:app --reload
On first run the browser opens for OAuth. After approving, token.json is saved and reused.
The OAuth token requests Google Docs access plus Gmail's gmail.compose scope, which supports both draft creation and message sending.
curl http://localhost:8000/health
# → {"status":"ok"}
Environment Variables
| Variable | Default | Description |
|---|---|---|
SERVER_API_KEY | (unset) | Server-side secret. When set, all endpoints require the HTTP header X-Api-Key: <value> |
APPROVAL_MODE | terminal | terminal = operator prompt in TTY; auto = approve all (required on Cloud Run) |
GOOGLE_CREDENTIALS_PATH | credentials.json | Path to OAuth client credentials (local dev) |
GOOGLE_TOKEN_PATH | token.json | Path to cached OAuth token (local dev) |
GOOGLE_CREDENTIALS_JSON | (unset) | Raw JSON content of credentials.json — injected by Cloud Run from Secret Manager |
GOOGLE_TOKEN_JSON | (unset) | Raw JSON content of token.json — injected by Cloud Run from Secret Manager |
PORT | 8000 | HTTP listen port — Cloud Run injects this automatically |
SERVER_API_KEYvsX-Api-Key:SERVER_API_KEYis the environment variable the server reads.X-Api-Keyis the HTTP request header clients must send. They are not the same thing — do not addX-API-KEYas an env var.
Copy .env.example to .env and fill in values for local development.
API Reference
All mutating endpoints require X-Api-Key when SERVER_API_KEY is set.
Append to a Google Doc
SERVICE_URL="https://mcp-server-google-695514226672.europe-west1.run.app"
API_KEY="PASTE_YOUR_API_KEY_HERE"
cat > payload.json <<'EOF'
{"doc_id":"YOUR_GOOGLE_DOC_ID","content":"# Section\n\n**Key point:** something important.\n\n- Item one\n- Item two"}
EOF
curl -i -X POST "$SERVICE_URL/append_to_doc" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $API_KEY" \
--data-binary @payload.json
{"status": "ok", "doc_id": "YOUR_DOC_ID", "chars_added": 58}
doc_id comes from your Doc URL: https://docs.google.com/document/d/{doc_id}/edit
Create a Gmail draft
SERVICE_URL="https://mcp-server-google-695514226672.europe-west1.run.app"
API_KEY="PASTE_YOUR_API_KEY_HERE"
cat > payload.json <<'EOF'
{"to":"recipient@example.com","subject":"Project Update","body":"# Project Update\n\n**Status:** On track\n\n- Milestone A complete\n- Milestone B in progress\n\n*Regards*"}
EOF
curl -i -X POST "$SERVICE_URL/create_email_draft" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $API_KEY" \
--data-binary @payload.json
{"status": "ok", "draft_id": "r12345abc"}
The draft appears in Gmail → Drafts with full HTML formatting (600 px card, proper heading hierarchy, bullet lists).
Send a Gmail message
Use the same payload as draft creation, but call the send endpoint:
curl -i -X POST "$SERVICE_URL/send_email" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $API_KEY" \
--data-binary @payload.json
{"status": "ok", "message_id": "18f...", "thread_id": "18f..."}
Health check (no auth required)
curl https://mcp-server-google-695514226672.europe-west1.run.app/health
# → {"status":"ok"}
Interactive docs: http://localhost:8000/docs (local only)
Tests
python -m pytest tests -q
The current suite contains 6 tests covering authentication, approval behavior, document append, Gmail draft creation, and Gmail sending.
Docker
# Pre-generate token.json on a machine with a browser (one-time)
python -c "from auth import get_credentials; get_credentials()"
# Build
docker build -t google-mcp-server .
# Run — mount credentials at runtime, never bake them into the image
docker run -d \
--name google-mcp-server \
-p 8000:8000 \
-e SERVER_API_KEY=your-secret-key \
-e APPROVAL_MODE=auto \
-e GOOGLE_CREDENTIALS_PATH=/secrets/credentials.json \
-e GOOGLE_TOKEN_PATH=/secrets/token.json \
-v /path/to/credentials.json:/secrets/credentials.json:ro \
-v /path/to/token.json:/secrets/token.json \
google-mcp-server
Deploy to Cloud Run
The service is live and continuously deployed via Cloud Run's built-in GitHub integration.
| Detail | Value |
|---|---|
| Project | NextLeap (gen-lang-client-0491576843) |
| Service | mcp-server-google |
| Region | europe-west1 |
| URL | https://mcp-server-google-695514226672.europe-west1.run.app |
| Deployment | Cloud Run built-in CD: push to main → Cloud Build → Cloud Run |
| Auth | Allow unauthenticated at Cloud Run level; app enforces X-Api-Key on mutating endpoints |
How it works
- Push to
main→ Cloud Build triggers automatically - Cloud Build builds the Docker image and pushes it to Artifact Registry (managed automatically)
- Cloud Run deploys the new revision
- At startup,
start.shwritesGOOGLE_CREDENTIALS_JSONandGOOGLE_TOKEN_JSON(from Secret Manager) to/tmp, sets path env vars, then starts uvicorn
Cloud Run environment
| Variable | Source | Value |
|---|---|---|
APPROVAL_MODE | Plain env var | auto |
GOOGLE_CREDENTIALS_JSON | Secret Manager: google-mcp-credentials:latest | Raw credentials.json content |
GOOGLE_TOKEN_JSON | Secret Manager: google-mcp-token:latest | Raw token.json content |
SERVER_API_KEY | Secret Manager: google-mcp-api-key:latest | Backend API key |
For the full setup guide, API key rotation, log commands, and troubleshooting see deployment_plan.md.
Security
| File | Purpose | Committed? |
|---|---|---|
credentials.json | OAuth 2.0 client secret | No — .gitignore |
token.json | Cached user OAuth token | No — .gitignore |
.env | Local secrets | No — .gitignore |
SERVER_API_KEYis stored in Google Secret Manager in production — never in code or committed filesAPPROVAL_MODE=terminalis the safe default locally — requires explicitybefore any Google API call- Cloud Run provides managed TLS on
*.run.appautomatically - No GitHub Actions, no
GCP_SA_KEY/GCP_PROJECT_IDsecrets needed in GitHub