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 only addition is a required account parameter on every tool (plus account: "all" fan-out on search_threads).

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.
• /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.

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.