Skip to main content
Glama
gmail-mcp

gmail-mcp

by tavoyne

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/<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. The signature sits in the path, not a query param, because agent hosts such as OpenClaw mask secret-looking query params before the model sees the link.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Gmail MCP server running on Cloudflare Workers that enables reading, searching, labeling, drafting, sending, and managing Gmail messages, including fetching raw attachment bytes, with per-user OAuth authorization.
      1
      -
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server that connects Gmail to AI assistants, enabling search, read, send, reply-all, forward, attachment handling, and draft management across multiple Google accounts, deployable on your own Cloudflare Worker.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Deployable MCP server on Cloudflare Workers that connects Gmail to AI assistants, enabling search, read, send, reply-all, forward, attachment handling, and label/thread management across multiple Google accounts simultaneously.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A Cloudflare Workers-based MCP server that connects Gmail to AI assistants, enabling search, read, send, reply-all, forward, and management of messages, drafts, labels, and threads across multiple Google accounts simultaneously.
      MIT