gmail-mcp

为你的 AI 助手准备的 Gmail——同时管理多个账户，运行在你自己的服务器上。

日本語版 · 简体中文

gmail-mcp 将 Gmail 连接到 Claude 和任何其他 MCP 客户端。它可以搜索和阅读邮件、发送和全部回复（带引用历史）、转发、处理附件和内联图片，并管理草稿、标签和会话——同时跨多个 Google 账户。

它作为远程服务器运行在你自己的 Cloudflare Worker 上，因此同一个连接可以从笔记本电脑上的 Claude Code、浏览器中的 claude.ai 以及手机上的 Claude 访问。每个连接登录一个 Google 账户，而 Google 刷新令牌则保留在你的 Cloudflare 账户中。

有两件事促使人们使用它。Claude 和 Google 内置的 Gmail 连接器可以读取邮件和编写草稿，但无法发送，并且每个助手账户只能绑定一个 Google 账户。能够发送邮件的服务器通常是本地进程——在办公桌前没问题，但在手机上就不可见了。

对比

google_workspace_mcp 是这里最完整的项目。它涵盖了整个 Workspace 而不仅仅是 Gmail，并且它会附加你的 Gmail 签名并从 URL 直接拉取附件，而 gmail-mcp 两者都不做。shinzo-labs/gmail-mcp 通过其 64 个工具访问假期回复、委托和 S/MIME；这些工具位于 gmail.settings.* 下，这是 gmail-mcp 从未请求的作用域，因此无论授权如何变化，它们都超出了其能力范围。

两个设计差异决定了其余大部分差异。通过调用参数路由账户可以让一个授权访问所有已连接的邮箱，而将邮箱绑定到连接则意味着错误的参数不会访问到任何内容。在读取方面，本地服务器将每个部分都解码为 UTF-8：ISO-2022-JP 和 Shift_JIS 邮件会乱码，而 Gmail 存储为附件块的较长消息会返回空正文。

部署

大约需要十分钟。你需要一个 Cloudflare 账户、bun 和一个 Google 账户。Cloudflare 账户上的域名是可选的——如果没有，Worker 将在 workers.dev 上响应。

1 · 创建 Google OAuth 客户端

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

Google 没有为接下来的两个步骤提供 API，因此它们需要在 Cloud 控制台 中完成：

• OAuth 同意屏幕 → 外部，然后在 受众群体 下点击 发布应用。如果保持在“测试”状态，Google 会在 7 天后让每个刷新令牌过期，每一条连接都会随令牌一起失效。发布后，应用在登录时会显示未经验证应用警告，并且最多可服务 100 个账户。

• 凭据 → 创建凭据 → OAuth 客户端 ID → Web 应用，以 https://<your-host>/callback 作为授权重定向 URI。请妥善保存客户端 ID 和机密。

<your-host> 是你指向该 Worker 的域名，或者 Worker 部署后默认获得的 workers.dev 主机名。先部署、再回来填写也可以——Worker 在 / 上提供的指南会显示具体值。

2 · 部署 Worker

这个按钮会将仓库复制到你的 GitHub 账户，创建 KV 命名空间和 Durable Object，并要求输入四个机密值。它会部署到 workers.dev；之后可以在 设置 → 域名与路由 下绑定自定义域名。

也可以选择在终端操作：

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

bun run setup 会询问要响应哪个域名、创建或复用 OAUTH_KV 命名空间、读取客户端 ID 和机密、生成 Cookie 密钥，然后进行部署。前两个回答会写入 wrangler.local.jsonc，该文件会被 git 忽略。wrangler.jsonc 中没有任何账户的命名空间，也没有任何用户的域名，因此克隆后可以部署到任何地方。重新运行 setup 以轮换单个机密值是安全的。

3 · 连接客户端

让客户端 ID 和机密字段留空——MCP 客户端会自行注册。

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

在 Claude Code 中运行 /mcp 即可将每条连接登录到其 Google 账户。在 claude.ai 中是 设置 → 连接器 → 添加自定义连接器，填入的 URL 相同。/mcp/ 之后的任意单段标签均可用，这样一次部署就能为拒绝两个服务器共用同一 URL 的客户端服务多个邮箱。

你的部署会在 https://<your-host>/ 上显示本指南。

它能做什么

whoami search_messages get_message get_thread get_attachment

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

list_labels create_label update_label delete_label modify_labels modify_thread_labels batch_modify_messages trash_message · untrash_message trash_thread · untrash_thread

发送的邮件与邮件客户端的发送方式一致：纯文本和 HTML 备用形式、文件附件，以及通过 cid: 引用的内联图片，按 multipart/mixed › multipart/related › multipart/alternative 嵌套。主题和显示名称使用 RFC 2047，文件名使用 RFC 2231，因此日语、中文和 emoji 都能完好保留。

reply_all 会读取原邮件的 Reply-To、From、To 和 Cc，排除自己的地址以及你用作发件地址的任何地址，从发件人当初写给你的那个地址回复，携带 References 链条，并在你发送的各个段落中引用原文。forward_message 会重现所转发的信封，并且可以重新附着原邮件的附件。

create_draft 配合 replyToMessageId 会把答复写成草稿，便于发送前编辑：它会加入原邮件的会话线程，保留 In-Reply-To 和 References，推导出“回复所有人”的收件人和 Re: 主题，并引用原邮件。update_draft 只修改传入的字段；由任何客户端手动添的收件人、文本、附件，以及草稿所回复的线程，都会被读取并保留。如果某个文件的 base64 无法塞进工具参数，则改为分段暂存：stage_attachment_begin 返回一个上传 URL，可以用一次 curl -T 发送原始字节；stage_attachment_append 分块接收 base64；任何 attachments 字段都接受生成的 stagingId。

读取范围是刻意限制的：邮件和邮件正文有字符预算，整个响应有字节上限，附件只有在足够小、能被读取时才以内联方式返回。冗长的邮件列表线程或大文件会被截断并附上说明，而不是撑满助手的上下文。

工作原理

两个 OAuth 流程汇聚在一个 Worker 中。MCP 客户端向 Worker 认证；Worker 代你向 Google 认证。双方都不会持有对方的机密。

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 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->>C: MCP access token (Google tokens sealed inside the grant)
    C->>W: POST /mcp — tools/call
    W->>G: Gmail REST (token refreshed as needed)
    G->>W: message / thread / label data
    W->>C: tool result

构建技术

• TypeScript + Cloudflare Workers——Durable Objects 每个持有一个 MCP 会话，KV 保存 OAuth 授权

• Hono —— 为 OAuth 端点、Google 回调和 / 上的设置页提供路由

• @cloudflare/workers-oauth-provider —— MCP 客户端所注册的 OAuth 2.1 服务器

• agents —— McpAgent，基于 Durable Objects 的 MCP 传输层

• @modelcontextprotocol/sdk + Zod —— 工具定义与参数校验

• Bun、Biome、Wrangler —— 安装、测试、lint、部署

Gmail 本身是通过对 REST API 的普通 fetch 调用的。官方 googleapis 库假定运行在 Node 环境，携带体积远非 Worker“所”。因此，邮件构造、MIME 解析和令牌刷新改由 src/gmail.ts 和 src/utils.ts 完成。

端点

谁可以登录

ALLOWED_EMAILS 决定身份，并会与 Google 报告为已验证的地址进行核对——在用户同意之后、任何授权存在之前。

每个授权只触及其完成身份验证的那个邮箱，因此扩大这个列表决不会扩大对已连接邮箱的访问范围。设置为 * 会让陌生人把你的部署以及你的 Google 客户端配额用来处理他们自己的邮件。

限制

两个上限让共享部署不会被抽干，两者都配置在 wrangler.jsonc 中：

在 Workers 免费计划中还有一层额外的限制：每次调用最多 50 个出站请求。一次大范围读取每条消息会消耗一个请求，因此 search_messages 和 list_drafts 在该计划下需要将 maxResults 设为 45 或更低；超过这个值，富余的部分不会作为结果返回，而会逐条报错。付费计划允许 1000 个。

提高这两个限制中的任意一个，然后重新部署。Cloudflare 的限流器在构建时从绑定中读取上限，因此每个绑定上的 simple.limit 是唯一需要修改的地方。对于单用户部署，两者都可以不动——正常助手使用量远远低于这些上限。

安全

自托管并不会消除信任问题，而只是转移了它，所以这里有各项的具体说明。

• 你的令牌始终属于你。 刷新令牌在其 OAuth 授权中被加密，存放在你的 KV 命名空间里。会话的 Durable Object 持有有效期为一小时的访问令牌，而 MCP 代理框架会在该对象存续期间保留该授权的一份副本，其中也包括刷新令牌。两处存储都在你自己的 Cloudflare 账户内，并且在静态存储时加密。邮件永远不会被存储——它只是从其中穿过。

• 一个会话对应一个邮箱。 MCP 会话与创建它的账户绑定，因此一个邮箱的授权无法通过借用的 session id 作用到另一个邮箱上。

• 最小化授权范围。 gmail.modify 包含读取、发送、标签和回收站操作。它不包含永久删除以及任何 gmail.settings.* 权限，因此自动转发规则和过滤器数据外泄——这些经典的邮箱后门——都不在任何被窃授权所能触发的范围之内。与此同时还会请求两个只读 scope，即 userinfo.email 和 userinfo.profile：allowlist 和会话绑定正是靠它们来判断哪个账户登录了，而它们并不触及任何邮件。

• 标头无法被夹带。 凡是包含 CR、LF 或 NUL 的出站标头值都会遭到拒绝，因此任何参数都无法从自己的文件夹中"逃逸"以附加一个新标头——比如在邮件主题里偷偷加上一个 Bcc。媒体类型会经过验证，引用的历史记录会进行 HTML 转义。但是，它并不会限制参数本身：bcc 是一个真实存在的参数，所以一个指令被藏在消息正文里的模型仍有可能把它填进去，同时你还需要客户端批准提示来把控这一点。

• 访问权限可以撤回。 缩小 ALLOWED_EMAILS 的范围即可阻止新的登录。单个账户的访问权限可在 myaccount.google.com/connections 撤销。轮换 Google 客户端密钥会让所有已创建的授权一次性全部失效。

Worker 在响应时为在内存中解密邮件，任何托管中继服务都是如此。如果某个特定邮箱无法接受这种方案，就建议为该邮箱在本机运行一个本地 MCP 服务器。

测试方式

253 个单元测试覆盖了消息构造（MIME 嵌套、RFC 2047 折行、RFC 2231 文件名、CR/LF 拒绝、base64 分块）、跨字符集的正文提取、回复与转发合成、Google 令牌测试、登录 allowlist、CSRF 以及保护登录流程浏览器端的 state 绑定检查、还有工具本身在模拟 Gmail 上面的表现，包括会话归属、收件人组合、附件选择以及部分读取失败的时候返回了什么。

除此之外，每个工具都曾对真实的 Gmail 账户实测，同时用另一个账户来确认发送的邮件是否真的到达：

开发

bun run dev     # wrangler dev on :8788
bun run check   # biome + tsc
bun test        # 253 unit tests
bun run assets  # regenerate the light and dark diagrams
bun run deploy

问题与 bug

请在 issue 中提交问题。

许可证

Copyright © 2026 mkpoli, 以 MIT License 发布。

src/workers-oauth-utils.ts 是从 cloudflare/ai 仓库中的 remote-mcp-github-oauth demo 派生而来的，Copyright © 2025 Cloudflare, Inc.，同样依照 MIT License 使用。请参阅 THIRD-PARTY.md。