A remote MCP server for Gmail, deployed on Cloudflare Workers, for use as a
custom connector in claude.ai (web/desktop/mobile) — built because the
official Gmail connector only supports one account at a time. This one lets
a single connector authorization manage (personal, work, side project, ...), with tools that let Claude
pick which account to act on.
Remote MCP server for Gmail with support for multiple connected accounts, deployed on Cloudflare Workers, for use as a claude.ai custom connector
星數
4
工具
—
可用率
—
any number of connected Gmail
accounts
Each user who connects authorizes their own Google account(s) via OAuth —
the server proxies that OAuth flow and never sees your Google password, just
the refresh tokens it needs to call the Gmail API on your behalf.
Setting this up with an AI coding agent? Clone the repo and just ask
it (e.g. "help me set up this MCP server") — it can run the npm/
wrangler commands below and edit wrangler.jsonc itself. See
AGENTS.md for exactly what it can automate versus what
needs you in a browser (the Google Cloud Console steps and the
claude.ai connector step).
Architecture
@cloudflare/workers-oauth-provider — implements the OAuth 2.1 server
that claude.ai talks to (authorize/token/dynamic client registration), and
hands your Worker an encrypted props bag identifying the connector
owner (email + name) once per authorized Claude session.
google-handler.ts — a small Hono app that owns /authorize and
/callback: shows the consent screen, redirects to Google, exchanges the
code for tokens. The first Google account signed in here both establishes
the owner's identity and is registered as their first connected Gmail
account.
accounts.ts — the multi-account store. Connected Gmail accounts
(email + refresh token) are kept in KV, keyed by owner, independent of the
Worker's own OAuth session lifetime — this is what makes "more than one
Gmail account" possible at all, since a single Google OAuth consent screen
can only ever authorize one account at a time.
accounts-handler.ts — the "connect another Gmail account" flow.
The get_gmail_connect_link tool mints a one-time link; opening it starts
a fresh Google OAuth round trip (with the account chooser forced open),
and the resulting refresh token is added to the same owner's account list
in KV — it does not touch the Claude-facing OAuth session at all.
agents' McpAgent — a Durable Object-backed MCP server. Tool calls
resolve which connected account to use (accounts.ts's resolveAccount),
mint that account a fresh Google access token on demand (cached in-memory
per Worker isolate), and call the Gmail API (gmail.ts).
Schema and tool names mirror Anthropic's official single-account Gmail
connector (so knowledge/prompts transfer directly), with an account
parameter layered on top of every tool below except account management.
Account management:
list_gmail_accounts — list connected accounts
get_gmail_connect_link — get a one-time link to connect another account
disconnect_gmail_account — remove a connected account
set_send_permission — allow/disallow the sending tools below (off by default)
Reading:
search_threads — search with Gmail's query syntax (or list recent inbox threads), with pagination
get_message / get_thread — a message or thread, at a chosen messageFormat (MINIMAL/FULL_CONTENT/METADATA_ONLY/PLAIN_TEXT)
Every tool other than the account-management ones takes an optional
account parameter — the Gmail address to act on. It's optional only when
exactly one account is connected; with more than one, omitting it returns an
error listing the connected accounts to choose from.
Compose tools (create_draft, update_draft, send_message, reply,
forward) accept both body (plain text) and htmlBody, plus attachments
(base64 content, optionally inline for images referenced via
cid:<filename> in htmlBody).
Sending is off by default
send_message, reply, and forward — anything that causes mail to
actually leave the account — are blocked until you (or Claude, on your
explicit say-so) call set_send_permission with allow: true. Until then,
calling any of them returns a message pointing Claude at create_draft
instead. This is a per-owner setting stored in KV (not per-deployment), so
it persists across Claude sessions and covers every connected account; call
set_send_permission with allow: false to turn it back off.
Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
Application type: Web application
Authorized redirect URIs: https://<your-worker-subdomain>.workers.dev/callbackandhttps://<your-worker-subdomain>.workers.dev/accounts/callback
(you'll know your Worker's URL after the first wrangler deploy — you
can add/edit these afterward in the Cloud Console).
Save the Client ID and Client Secret.
If your OAuth consent screen is in "Testing" mode, add every Google account
you plan to connect (not just your primary one) as test users. Note that
Testing mode also caps refresh tokens at 7 days, so every connected
account will need to be re-authorized weekly — publish the consent screen
to "Production" (OAuth consent screen → Publish App) to remove that
cap. Sensitive scopes like Gmail's will show an "unverified app" warning
on the consent screen unless you complete Google's verification, but you
can still click through it (Advanced → Go to [app]) for personal/internal
use.
npm install
cp wrangler.jsonc.example wrangler.jsonc # gitignored — this is your own config, not the repo's
npx wrangler login
npx wrangler kv namespace create OAUTH_KV
Copy the id printed by the last command into your wrangler.jsonc under both
kv_namespaces[0].id and env.development.kv_namespaces[0].id. This one KV
namespace stores both OAuth state and the connected-accounts data.
If npx wrangler whoami lists more than one Cloudflare account, add
"account_id" to your wrangler.jsonc (see the comment there) or set the
CLOUDFLARE_ACCOUNT_ID env var — otherwise wrangler can't tell which
account to deploy to.
Set secrets (each command prompts for the value on stdin):
npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY # e.g. output of: openssl rand -hex 32
Scripting this instead of typing interactively? Pipe the value in:
printf '%s' "$VALUE" | npx wrangler secret put NAME (and
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY for
the third one).
3. Deploy
npm run deploy
This prints your Worker's URL, e.g. https://mcp-gmail-multi-account.<your-subdomain>.workers.dev.
Go back to the Google Cloud Console and make sure the OAuth client's redirect
URIs are exactly <that-url>/callback and <that-url>/accounts/callback.
Then edit your wrangler.jsonc's top-level vars.PUBLIC_URL to that same
URL — it's used to build the "connect another Gmail account" link — and
redeploy (npm run deploy again).
4. Connect it to claude.ai
In claude.ai: Settings → Connectors → Add custom connector, and enter:
Claude will walk you through authorizing — you'll see the consent screen
from google-handler.ts, then Google's own OAuth screen. Once approved, the
Gmail tools are available, with that first Google account already connected.
5. Connect additional Gmail accounts
Ask Claude to connect another account (it'll call get_gmail_connect_link)
and open the link it gives you. Pick a different Google account at Google's
account chooser, approve, and it's added — no need to reauthorize the
Claude connector itself.
Local development
cp .env.development.example .env.development # fill in the same three values as the secrets above
npm run dev
wrangler dev runs the Worker locally; note that Google's OAuth redirects
must match what you're actually running against (add
http://localhost:8788/callback and http://localhost:8788/accounts/callback
as additional authorized redirect URIs in Google Cloud Console for local
testing).
Notes
Uses the https://www.googleapis.com/auth/gmail.modify OAuth scope (read,
compose, send, and organize mail, but not permanent delete) plus
email profile to identify each connecting account.
Google access tokens expire in ~1 hour; this server refreshes them on
demand from the stored refresh token, per connected account, rather than
syncing to this Worker's own OAuth token lifetime.
search_threads hydrates each result with a metadata fetch (subject,
from, to, date, snippet) since Gmail's threads.list only returns bare
thread ids — each call is capped at 50 results (pageSize), with
pageToken for further pages.
get_message/get_thread return attachment metadata (filename, type,
size, attachment id) but not content directly — forward downloads and
re-attaches a message's existing attachments itself.
See SECURITY.md for the account-linking flow's threat
model and how to report vulnerabilities.
Contributing
See CONTRIBUTING.md for local setup and the quality
checks (npm run check) to run before opening a PR.
上次檢查時間:2026-10-28。 Remote MCP server for Gmail with support for multiple connected accounts, deployed on Cloudflare Workers, for use as a claude.ai custom connector