gmail-mcp

Remote MCP server on Cloudflare Workers exposing multiple Gmail accounts to Claude through one connector. Tool names, descriptions, and response shapes replicate Anthropic's built-in Gmail connector; the additions are a required account parameter on every tool (plus account: "all" fan-out on search_threads) and get_message_attachment, which the built-in connector does not expose. That tool returns a short-lived signed download link rather than attachment content, so files reach disk without passing through the model's context.

Architecture

• /mcp: Streamable HTTP MCP endpoint. Two auth paths: MCP OAuth (what claude.ai uses; dynamic client registration + PKCE via workers-oauth-provider, with the /authorize approval page gated by SETUP_SECRET) or a static bearer secret (MCP_SECRET) for CLI clients and tests.

• /attachment?...&signature=<hmac>: serves one attachment's raw bytes. get_message_attachment mints these links, signing account, message id, attachment id and a 10-minute expiry with MCP_SECRET. The link carries its own authorization so a plain curl -o works, and within its window it unlocks that one attachment and nothing else.

• /connect/<alias>?key=<SETUP_SECRET>: browser route that runs the Google OAuth flow for one account and stores its refresh token in KV.

• /oauth/callback: Google OAuth redirect target.

• Tokens live in the GMAIL_KV namespace (refresh:<alias> plus a short-lived access:<alias> cache). Scope is gmail.modify: read, search, labels, drafts; no send.

• Requires a Workers paid plan: search_threads and list_drafts make one Gmail request per result, so a large pageSize (or account: "all") exceeds the free plan's 50-subrequest cap.

Related MCP server: gmail-mcp

Configuration

• ACCOUNTS var in wrangler.jsonc: comma-separated account aliases. Rerun npx wrangler deploy after changing it.

• Secrets (set with npx wrangler secret put <NAME>):

  • MCP_SECRET: bearer token Claude sends; anyone holding it can read the connected mailboxes.

  • SETUP_SECRET: gates the /connect routes.

  • GOOGLE_CLIENT_ID_<ALIAS> / GOOGLE_CLIENT_SECRET_<ALIAS> per account, alias uppercased (e.g. GOOGLE_CLIENT_ID_CANDIX).

Per-account Google setup (~10 min, once per Workspace org)

1. Go to https://console.cloud.google.com and create a project inside that Workspace org (top-left project picker > New project).

2. APIs & Services > Library > search "Gmail API" > Enable.

3. APIs & Services > OAuth consent screen: User type Internal (no verification, refresh tokens do not expire), fill in the app name and contact email.

4. APIs & Services > Credentials > Create credentials > OAuth client ID > Application type Web application. Add the authorized redirect URI: https://gmail-mcp.<your-subdomain>.workers.dev/oauth/callback.

5. Copy the client ID and secret into Worker secrets:

   npx wrangler secret put GOOGLE_CLIENT_ID_<ALIAS>
   npx wrangler secret put GOOGLE_CLIENT_SECRET_<ALIAS>

6. Visit https://gmail-mcp.<your-subdomain>.workers.dev/connect/<alias>?key=<SETUP_SECRET> in a browser while signed in to that Google account, and approve.

Re-run step 6 anytime to reconnect (e.g. after revoking access).

Connect to Claude

Settings > Connectors > Add custom connector:

• URL: https://gmail-mcp.<your-subdomain>.workers.dev/mcp

• Leave the OAuth client ID/secret fields empty (Claude registers itself dynamically).

• Click Add, then Connect: an approval page opens; paste SETUP_SECRET and approve.

The connector then works on claude.ai web, mobile, desktop, and Claude Code.

Rotating the bearer secret

npx wrangler secret put MCP_SECRET

Then update the Authorization header in the Claude connector settings.