convez.ai
MCP Server
md-ammar-97

mcp-server-google

md-ammar-97/mcp-server-google

Ver no GitHub
InicialPluginScore · de 0 a 100

Instalação

$npx convez-ai md-ammar-97/mcp-server-google

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 Doc
  • POST /create_email_draft — create a styled HTML Gmail draft
  • POST /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-Key request 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:

SyntaxOutput
# H1 / ## H2 / ### H3Docs: named heading style · Email: <h1>–<h3>
- item or * itemDocs: 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

  1. Go to Google Cloud Console → APIs & Services → Library
  2. Enable Google Docs API and Gmail API
  3. Go to Credentials → Create Credentials → OAuth 2.0 Client ID
  4. Application type: Desktop app → Download JSON → save as credentials.json in the project root
  5. 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

VariableDefaultDescription
SERVER_API_KEY(unset)Server-side secret. When set, all endpoints require the HTTP header X-Api-Key: <value>
APPROVAL_MODEterminalterminal = operator prompt in TTY; auto = approve all (required on Cloud Run)
GOOGLE_CREDENTIALS_PATHcredentials.jsonPath to OAuth client credentials (local dev)
GOOGLE_TOKEN_PATHtoken.jsonPath 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
PORT8000HTTP listen port — Cloud Run injects this automatically

SERVER_API_KEY vs X-Api-Key: SERVER_API_KEY is the environment variable the server reads. X-Api-Key is the HTTP request header clients must send. They are not the same thing — do not add X-API-KEY as 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.

DetailValue
ProjectNextLeap (gen-lang-client-0491576843)
Servicemcp-server-google
Regioneurope-west1
URLhttps://mcp-server-google-695514226672.europe-west1.run.app
DeploymentCloud Run built-in CD: push to main → Cloud Build → Cloud Run
AuthAllow unauthenticated at Cloud Run level; app enforces X-Api-Key on mutating endpoints

How it works

  1. Push to main → Cloud Build triggers automatically
  2. Cloud Build builds the Docker image and pushes it to Artifact Registry (managed automatically)
  3. Cloud Run deploys the new revision
  4. At startup, start.sh writes GOOGLE_CREDENTIALS_JSON and GOOGLE_TOKEN_JSON (from Secret Manager) to /tmp, sets path env vars, then starts uvicorn

Cloud Run environment

VariableSourceValue
APPROVAL_MODEPlain env varauto
GOOGLE_CREDENTIALS_JSONSecret Manager: google-mcp-credentials:latestRaw credentials.json content
GOOGLE_TOKEN_JSONSecret Manager: google-mcp-token:latestRaw token.json content
SERVER_API_KEYSecret Manager: google-mcp-api-key:latestBackend API key

For the full setup guide, API key rotation, log commands, and troubleshooting see deployment_plan.md.


Security

FilePurposeCommitted?
credentials.jsonOAuth 2.0 client secretNo — .gitignore
token.jsonCached user OAuth tokenNo — .gitignore
.envLocal secretsNo — .gitignore
  • SERVER_API_KEY is stored in Google Secret Manager in production — never in code or committed files
  • APPROVAL_MODE=terminal is the safe default locally — requires explicit y before any Google API call
  • Cloud Run provides managed TLS on *.run.app automatically
  • No GitHub Actions, no GCP_SA_KEY / GCP_PROJECT_ID secrets needed in GitHub
Ver o original no GitHub

Relacionados