
Gmail Mcp
io.github.mkpoli由 GitHub 帳號 mkpoli 發布v0.3.0更新於 Oct 31, 2026
Multi-account Gmail on a Cloudflare Worker you deploy yourself: read, send, reply, labels, threads
概覽
部署在自己 Cloudflare Worker 上的 Gmail MCP 伺服器:可讀取、寄送、回覆、轉寄並整理多個 Google 帳號的信件。
- 可以做什麼
- 搜尋、讀取郵件、討論串與附件,並確認目前登入的帳號
- 寄送郵件、附引用歷史的全面回覆、轉寄,以及管理草稿(含分段上傳大型附件)
- 列出、建立、修改、刪除標籤,批次套用標籤,以及將郵件或討論串移至/移出垃圾桶
- 回應長度受字元與位元組上限限制,較大檔案以短時有效的下載連結回傳
- 適用情境
- 當助理需要真正寄出或回覆 Gmail 信件而不只是寫草稿,或希望一次部署同時服務多個 Google 信箱、在筆電、瀏覽器與手機上都能使用時。也適合希望 Google 重新整理權杖留在自己 Cloudflare 帳號的情況。
- 執行需求
- 需要 Cloudflare 帳號、bun 與 Google 帳號;需建立 Google OAuth 用戶端 ID 與密鑰,並將 Worker 的回呼位址設為重新導向 URI;OAuth 同意畫面需發布。透過部署按鈕或 bun run setup 部署,會寫入密鑰並建立 KV 命名空間與 Durable Object。用戶端以 HTTP 連線 Worker 的 /mcp 路徑,並逐一連線登入;ALLOWED_EMAILS 決定誰可登入。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Gmail Mcp,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
Gmail for your AI assistant — several accounts at once, on a server you own.
[MIT] [Cloudflare Workers] [MCP] [OAuth 2.1] [27 tools] [tests]
[An assistant searches a work and a personal mailbox, then replies to a thread with an attachment]
gmail-mcp connects Gmail to Claude and any other MCP client. It can search and read mail, send and reply-all with quoted history, forward, handle attachments and inline images, and manage drafts, labels, and threads — across several Google accounts at the same time.
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 the Google refresh token stays in your Cloudflare account.
Two things push people here. The Gmail connectors built into Claude and Google read mail and write drafts, but cannot send, and hold one Google account per assistant account. Servers that can send are usually local processes — fine at a desk, invisible from a phone.
How it compares
[gmail-mcp compared with built-in connectors, google_workspace_mcp, and Gmail-MCP-Server]
A longer comparison — six projects, twelve rows
google_workspace_mcp is the most complete project here. It covers all of Workspace rather than Gmail alone, and it appends your Gmail signature and pulls attachments straight from a URL, neither of which gmail-mcp does. shinzo-labs/gmail-mcp reaches vacation responders, delegates, and S/MIME through its 64 tools; those live under gmail.settings.*, a scope gmail-mcp never requests, so they stay beyond its reach whatever happens to a grant.
Two design differences decide most of the rest. Routing accounts by a call argument lets one grant touch every connected mailbox, while binding the mailbox to the connection means a wrong argument reaches nothing. And on reading, the local servers decode every part as UTF-8: ISO-2022-JP and Shift_JIS mail arrives garbled, and long messages that Gmail stores as attachment blobs come back with an empty body.
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
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>/callbackas 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:
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.
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.
Your deployment serves this guide at https://<your-host>/.
What it can do
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; when they cannot all go, nothing is sent.
create_draft with replyToMessageId writes the reply as a draft to edit before sending: it joins the original's thread, carries In-Reply-To and References, derives the reply-all recipients and the Re: subject, and quotes the original. update_draft changes only the fields it is given; recipients, text, files added by hand in any client, and the thread the draft answers are read back and kept. 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, stage_attachment_append takes base64 in chunks, and every attachments field accepts the resulting stagingId.
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. A long mailing-list thread comes back trimmed with a note saying so rather than filling the assistant's context. A larger file comes back as a download link that works for an hour while the session stays open, and curl -o saves it to disk without its bytes passing through the conversation.
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.
[An MCP client connects to your Cloudflare Worker, which calls the Gmail API]
Built with
- TypeScript on Cloudflare Workers — Durable Objects hold one MCP session each, KV holds the OAuth grants
- Hono — routing for the OAuth endpoints, the Google callback, and the setup page at
/ @cloudflare/workers-oauth-provider— the OAuth 2.1 server that MCP clients register againstagents—McpAgent, the MCP transport over Durable Objects@modelcontextprotocol/sdkwith Zod — tool definitions and argument validation- Bun, Biome, Wrangler — install, test, lint, deploy
Gmail itself is called over plain fetch against the REST API. The official googleapis SDK assumes Node and carries far more than a Worker should ship, so message building, MIME parsing, and token refresh live in src/gmail.ts and src/utils.ts instead.
Endpoints
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, so widening this list never widens access to mailboxes already connected. Setting * lets strangers use your deployment, and your Google client's quota, for their own mail.
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. A wide read spends one per message, so search_messages and list_drafts want maxResults at 45 or below there; above it the surplus comes back as per-message errors rather than results. The paid plan allows 1000.
Raise either and redeploy. Cloudflare's rate limiter reads its ceiling from the
binding at build time, so the simple.limit on each is the only place that
changes it. A
single-user deployment can leave both alone — normal assistant use sits far
below them.
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. A session's Durable Object holds the hour-lived access token, and the MCP agent framework keeps a copy of the grant there for as long as the object lives, refresh token included. Both stores are your own Cloudflare account, encrypted at rest. Mail is never stored — it passes through.
- One session, one mailbox. The MCP session is bound to the account that opened it, so a grant for one mailbox cannot act on another through a borrowed session id.
- Scope minimalism.
gmail.modifycovers reading, sending, labels, and trash. It excludes permanent deletion and all ofgmail.settings.*, keeping auto-forwarding rules and filter exfiltration — the classic mailbox backdoors — outside what any stolen grant could do. Two read-only scopes are requested alongside it,userinfo.emailanduserinfo.profile: they are how the allowlist and the session binding know which account signed in, and they reach no mail. - Headers cannot be smuggled. Every outgoing header value is rejected if it contains CR, LF or NUL, so no argument can break out of its own field to append one — a
Bccinside a subject line, say. Media types are validated, and quoted history is HTML-escaped. What this does not do is police the arguments themselves:bccis a real parameter, so a model acting on an instruction hidden in a message body could still fill it in, and your client's approval prompt remains the check on that. - Access can be withdrawn. Narrowing
ALLOWED_EMAILSstops 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
260 unit tests cover message construction (MIME nesting, RFC 2047 folding, RFC 2231 filenames, CR/LF rejection, base64 wrapping), body extraction across charsets, reply and forward composition, the Google token flows, the sign-in allowlist, the CSRF and state-binding checks that guard the browser side of sign-in, and the tools themselves against a stand-in Gmail — session ownership, recipient composition, attachment selection, and what a partly-failed read returns.
Beyond that, every tool has run against real Gmail accounts, with a separate account checking what arrived:
Development
Questions and bugs
Open an issue.
License
Copyright © 2026 mkpoli. Released under the MIT License.
src/workers-oauth-utils.ts is derived from the remote-mcp-github-oauth demo in cloudflare/ai, Copyright © 2025 Cloudflare, Inc., used under the MIT License. See THIRD-PARTY.md.
來源:README.md,提交 27f06e7
工具
0版本歷史
2- v0.3.0最新Oct 17, 2026
- v0.2.1Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分