gmail-mcp-plus

Gmail and Calendar for your AI assistant — every account at once, on a server you own.

gmail-mcp-plus connects Gmail and Google Calendar to Claude and any other MCP client. It can search and read mail — in one account or across every connected account at once — send, reply-all, and forward with quoted history, handle attachments and inline images, manage drafts, labels, threads, and filters, unsubscribe from mailing lists by their own one-click headers, and read, create, and answer calendar events.

It runs as a remote server on your own Cloudflare Worker, so the same connection answers from Claude Code on a laptop, claude.ai in a browser, and Claude on a phone. Each connection signs in to one Google account and can carry a friendly alias ("work", "personal"); the Google refresh tokens stay encrypted in your Cloudflare account.

This project is a fork of mkpoli/gmail-mcp (MIT), which contributes the entire Gmail core, the two-sided OAuth machinery, and the session model. The fork exists to close the feature gaps the upstream deliberately or historically left open:

Every feature is a deployment flag (ENABLE_FILTERS, ENABLE_CALENDAR, ENABLE_CROSS_ACCOUNT, all "true" by default), and each flag brings exactly its own Google scopes — turn one off and sign-in never asks for what it will not use.

Deploy it

About ten minutes. You need a Cloudflare account, bun, and a Google account. A domain on the Cloudflare account is optional — without one the Worker answers on workers.dev.

1 · Create a Google OAuth client

PROJECT="gmail-mcp-$(openssl rand -hex 3)"
gcloud auth login
gcloud projects create "$PROJECT" --name="gmail-mcp-plus"
gcloud config set project "$PROJECT"
gcloud services enable gmail.googleapis.com calendar-json.googleapis.com

Google exposes no API for the next two steps, so they happen in the Cloud console:

• OAuth consent screen → External, then under Audience press Publish app. Left in Testing, Google expires every refresh token after 7 days and each connection dies with its token. Published, the app shows an unverified-app warning at sign-in and serves up to 100 accounts.

• Credentials → Create credentials → OAuth client ID → Web application, with https://<your-host>/callback as an authorized redirect URI. Keep the client ID and secret.

<your-host> is the domain you point at the Worker, or the workers.dev hostname it gets otherwise. Deploying first and coming back to fill this in works — the guide the Worker serves at / shows the exact value.

2 · Deploy the Worker

The button copies the repository into your GitHub account, creates the KV namespace and the Durable Object, and asks for the four secrets. It deploys to workers.dev; a custom domain is attached afterwards under Settings → Domains & Routes.

From a terminal instead:

git clone https://github.com/BowTiedSwan/gmail-mcp-plus && cd gmail-mcp-plus
bun install
bun run setup

bun run setup asks which domain to answer on, creates or reuses the OAUTH_KV namespace, takes the client ID and secret, generates a cookie key, and deploys. Those first two answers land in wrangler.local.jsonc, which git ignores — wrangler.jsonc names no account's namespace and no one's domain, so a clone deploys anywhere. Re-running setup to rotate a single secret is safe.

3 · Connect a client

Leave the client ID and secret fields empty — MCP clients register themselves.

claude mcp add --transport http gmail-personal https://<your-host>/mcp
claude mcp add --transport http gmail-work     https://<your-host>/mcp/work

Run /mcp in Claude Code to sign each connection in to its Google account. In claude.ai it is Settings → Connectors → Add custom connector with the same URL. Any single-segment label works after /mcp/, which is how one deployment serves several mailboxes to clients that reject two servers sharing a URL.

Once two accounts are connected, give them names and search them together:

set_account_alias("work") · list_accounts · search_all_accounts("invoice newer_than:7d")

Your deployment serves this guide at https://<your-host>/.

Related MCP server: mcp-gsuite

What it can do

whoami search_messages get_message get_thread get_attachment get_unsubscribe_info

send_message reply_all forward_message create_draft update_draft send_draft delete_draft list_drafts stage_attachment_begin stage_attachment_append stage_attachment_finish unsubscribe

list_labels create_label update_label delete_label modify_labels modify_thread_labels batch_modify_messages mark_read · mark_unread trash_message · untrash_message trash_thread · untrash_thread list_filters create_filter delete_filter

list_accounts set_account_alias search_all_accounts list_calendars list_events get_event create_event update_event delete_event respond_to_event

Messages leave the way a mail client sends them: plain text with an HTML alternative, file attachments, and inline images referenced by cid:, nested as multipart/mixed › multipart/related › multipart/alternative. Subjects and display names use RFC 2047, filenames use RFC 2231, so Japanese, Chinese, and emoji survive the trip.

reply_all reads the original's Reply-To, From, To, and Cc, drops your own address and any address you send mail as, answers from the one the sender wrote to, carries the References chain, and quotes the original in whichever parts you send. forward_message reproduces the forwarded envelope and can re-attach the original's files. create_draft with replyToMessageId writes the reply as a draft to edit before sending. A file whose base64 will not fit through tool arguments is staged instead: stage_attachment_begin returns an upload URL that takes the raw bytes in one curl -T.

unsubscribe acts on the headers a mailing list publishes for machines — RFC 2369 List-Unsubscribe and RFC 8058 List-Unsubscribe-Post — never on tracking links in the body. A one-click sender gets a single https POST; a mailto sender gets a properly formed unsubscribe message from the account itself; a sender offering only a web page gets its URL handed back for a human. get_unsubscribe_info shows what would happen before anything does.

search_all_accounts runs one Gmail query against every account connected to the deployment, in parallel, each under its own rate budget, results grouped and labeled by alias. One dead mailbox reports its error in place rather than emptying the answer.

Calendar events round-trip with attendees, recurrence, and time zones: create_event refuses a zoneless local time before the API can garble it, update_event patches only what it is given, and respond_to_event answers an invitation as the connected account without disturbing the rest of the attendee list.

Reading is bounded on purpose: message and thread bodies have character budgets, a whole response has a byte ceiling, and an attachment is returned inline only while it stays small enough to read.

How it works

Two OAuth flows meet in one Worker. The MCP client authenticates to the Worker; the Worker authenticates to Google on your behalf. Neither side holds the other's credentials.

sequenceDiagram
    autonumber
    participant C as MCP client<br/>(Claude Code · claude.ai)
    participant W as Worker<br/>(OAuthProvider + McpAgent)
    participant G as Google<br/>(OAuth + Gmail/Calendar API)

    C->>W: POST /register (dynamic client registration)
    C->>W: GET /authorize (PKCE challenge)
    W->>C: approval dialog
    C->>G: consent screen — pick the account
    G->>W: GET /callback?code=…
    W->>W: allowlist check on the verified email
    W->>G: exchange code → access + refresh token
    W->>W: sealed registry record (aliases · cross-account)
    W->>C: MCP access token (Google tokens sealed inside the grant)
    C->>W: POST /mcp — tools/call
    W->>G: Gmail / Calendar REST (token refreshed as needed)
    G->>W: message / thread / event data
    W->>C: tool result

Gmail and Calendar are called over plain fetch against their REST APIs. The official googleapis SDK assumes Node and carries far more than a Worker should ship.

Endpoints

Feature flags

Three vars in wrangler.jsonc, all "true" by default. Changing one changes the scopes the next sign-in asks for; connections made before the change keep the scopes they were granted and are told to reconnect when a tool needs more.

The cross-account tradeoff, plainly. Upstream's rule is one session, one mailbox: a grant for one account can never touch another. Cross-account search necessarily crosses that line — at sign-in the account's refresh token is also written, AES-256-GCM-sealed, into the registry, and any connected session may then search (not send from, not modify) every registered mailbox. That is the right trade for one person's own accounts and the wrong one for a deployment shared between people who shouldn't read each other's mail: set ENABLE_CROSS_ACCOUNT to "false" there, and only aliases remain. On a deployment whose ALLOWED_EMAILS is *, cross-account is forced off whatever the flag says — a public relay where strangers search each other's mail is not a configuration, it is an incident.

Who can sign in

ALLOWED_EMAILS decides, checked against the address Google reports as verified — after consent, before any grant exists.

Each grant reaches only the mailbox that authenticated it — cross-account search aside, which is why that feature is a flag.

Limits

Two ceilings keep a shared deployment from being drained, both set in wrangler.jsonc:

On the Workers Free plan a further ceiling applies: 50 outbound requests per invocation, so search_messages and list_drafts want maxResults at 45 or below there, and search_all_accounts wants maxResultsPerAccount kept small with many accounts connected. The paid plan allows 1000.

Security

Self-hosting moves the trust question rather than removing it, so here is where everything sits.

• Your tokens stay yours. Refresh tokens are encrypted inside their OAuth grant in your KV namespace, and — with cross-account on — AES-256-GCM-sealed in the account registry under a key derived (HKDF) from COOKIE_ENCRYPTION_KEY. Both stores are your own Cloudflare account, encrypted at rest. Mail is never stored — it passes through.

• One session, one mailbox — for everything that writes. Sending, replying, drafts, labels, filters, and calendar changes only ever act on the account the session authenticated. Cross-account search is the sole, read-only, flag-gated exception.

• Scope minimalism, feature by feature. gmail.modify covers reading, sending, labels, and trash while excluding permanent deletion. Filters add gmail.settings.basic and not gmail.settings.sharing — forwarding addresses and delegates, the classic exfiltration backdoors, stay out of reach, and create_filter offers no forwarding action either. Calendar adds event rights without ACL, settings, or calendar-deletion rights. Turn a feature off and its scopes are never requested.

• Unsubscribe is screened. Only https targets with real hostnames are POSTed to — no http, no credentials in URLs, no IP literals, no localhost — and only when the sender declared RFC 8058 one-click. Everything else falls back to mailto or to a URL handed to a human.

• Headers cannot be smuggled. Every outgoing header value is rejected if it contains CR, LF or NUL — including addresses parsed out of a hostile List-Unsubscribe header. Media types are validated, and quoted history is HTML-escaped.

• Access can be withdrawn. Narrowing ALLOWED_EMAILS stops new sign-ins. A single account's access is revoked at myaccount.google.com/connections. Rotating the Google client secret invalidates every grant at once.

The Worker decrypts mail in memory while serving a request, as any hosted relay must. If that is unacceptable for a particular mailbox, run a local MCP server for that one.

How it was tested

305 unit tests cover message construction (MIME nesting, RFC 2047 folding, RFC 2231 filenames, CR/LF rejection), body extraction across charsets, reply and forward composition, the Google token flows, the sign-in allowlist, the CSRF and state-binding checks, the registry's seal/open round-trip and its refusal of tampered records, List-Unsubscribe parsing including header-injection attempts, feature-flag and scope resolution, and the tools themselves against a stand-in Gmail and Calendar — session ownership, cross-account grouping and token isolation, one-click POST bodies, filter validation, attendee patching, and what a partly-failed read returns.

Development

bun run dev     # wrangler dev on :8788
bun run check   # biome + tsc
bun test        # 305 unit tests
bun run deploy

Questions and bugs

Open an issue.

License

Released under the MIT License. Based on mkpoli/gmail-mcp, Copyright © 2026 mkpoli, MIT — see THIRD-PARTY.md, which also covers src/workers-oauth-utils.ts, derived from Cloudflare's remote-mcp-github-oauth demo.