gmail-mcp

为你的 AI 助手提供 Gmail 支持——同时管理多个账号，运行在你自己的服务器上。

日本語版 · 简体中文

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

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

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

对比

Related MCP server: Gmail MCP Connector

部署

大约十分钟。你需要一个 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 的域名，或者是它默认获得的 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，因此日文、中文和表情符号都能完好送达。

reply_all 会读取原邮件的 Reply-To、From、To 和 Cc，剔除你自己的地址以及你用来发送邮件的任何地址，从发件人最初写给的地址回复，携带 References 链，并在你发送的各个部分中引用原文。forward_message 会重现被转发邮件的信封结构，并可重新附上原邮件的文件。

带 replyToMessageId 的 create_draft 会把回复写入草稿，以便在发送前编辑：它会加入原邮件的会话线程，携带 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 Object 持有一个 MCP 会话，KV 保存 OAuth 授权（grant）

• Hono — 为 OAuth

在 Workers 免费套餐上还有一层上限：每次调用最多 50 个出站请求。一次广泛读取每条消息消耗一个请求，因此 search_messages 和 list_drafts 的 maxResults 需要设为 45 或更低；超过该值，多余的部分会以逐条消息的错误形式返回，而不是结果。付费套餐允许 1000。

调高任一上限并重新部署。Cloudflare 的速率限制器在构建时从绑定中读取其上限，因此每个绑定上的 simple.limit 是唯一能改变它的地方。单用户部署可以两者都不动——正常的助手使用远低于这些上限。

安全性

自托管只是转移了信任问题，而非消除它，所以这里说明一切所处的位置。

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

• 一个会话，一个邮箱。 MCP 会话绑定到打开它的账户，因此一个邮箱的授权无法通过借用的会话 ID 对另一个邮箱进行操作。

• 最小化权限范围。 gmail.modify 涵盖读取、发送、标签和垃圾箱。它排除永久删除以及所有 gmail.settings.*，使自动转发规则和过滤器外泄——经典的邮箱后门——超出任何被盗授权所能触及的范围。另有两个只读范围与之一起请求，userinfo.email 和 userinfo.profile：它们只是让允许列表和会话绑定知道是哪个账户登录，且不触及任何邮件。

• 标头无法被走私。 每个出站标头值若包含 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 令牌流程、登录允许列表、保护登录浏览器端的 CSRF 和状态绑定检查，以及针对模拟 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

问题与缺陷

请打开一个 issue。

许可证

版权所有 © 2026 mkpoli。以 MIT 许可证 发布。

src/workers-oauth-utils.ts 衍生自 cloudflare/ai 中的 remote-mcp-github-oauth 演示，版权所有 © 2025 Cloudflare, Inc.，按 MIT 许可证使用。参见 THIRD-PARTY.md。