google-mail-mcp

google-mail-mcp

将 Gmail 用作 MCP 工具。阅读邮件，但不让邮件读取你的助手。

这是一个通过标准输入输出与 MCP 通信的独立 Go 二进制文件。它作为客户端的子进程运行在你自己的机器上，访问你自己的 Google 账号。无需托管服务，也无需服务账号：创建一个 Google OAuth 客户端，登录一次，刷新令牌就会保存在你的操作系统密钥环中。

它仅在邮箱范围内运行。日历邀请中的活动、关联的 Drive 文件和 Chat 空间，属于基于这些 API 构建的服务。

为什么选择 google-mail-mcp

每封邮件都由别人撰写，其中有些内容旨在诱导 AI 助手采取特定行动。因此，邮件内容会放在带有每次调用专属边界令牌的区块中返回；邮件读者原本看不到的文本——隐藏样式、零宽字符、与背景同色的文字——会被移除并统计；邮件链接或嵌入的内容不会被获取；链接文本所指的网站与链接目标不同时，会予以标记。

可能让受诱导的助手变得危险的写入操作均未提供。自动转发、转发邮件的过滤器和委派功能均未实现；转发一封邮件时，它会被附加到草稿中。只有启用发送功能后，发送工具才会注册，而且只能发送草稿。删除操作会将邮件移至垃圾箱；只有启用永久删除功能后，永久删除工具才会注册，而它也是唯一需要向 Google 请求完整邮件访问权限的功能。

读取操作有界限。线程会在字符数预算内按时间倒序返回，并将引用回复和签名折叠为一行，说明隐藏了多少内容；每处省略都会说明如何继续查看。非 ASCII 主题、姓名和文件名均可按任意字符集解码。

安装

go install github.com/mmedum/google-mail-mcp/v3/cmd/google-mail-mcp@latest

也可以从最新版本下载压缩包——支持 Linux、macOS 和 Windows，适用于 amd64 和 arm64——并在运行前验证：

sha256sum -c checksums.txt --ignore-missing

# The checksum file is signed with a keyless Sigstore certificate tied to
# the release workflow's identity.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github\.com/mmedum/google-mail-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And the archive itself carries build provenance.
gh attestation verify google-mail-mcp_*.tar.gz --repo mmedum/google-mail-mcp

每个压缩包都附带 SBOM。构建可复现：重新构建某个标签会得到完全相同的字节。

Claude Desktop

每个版本还附带一个 .mcpb 套件。打开后，Claude Desktop 会安装 MCP 服务，并提示你填写客户端配置中需要的设置：OAuth 客户端 JSON、配置文件、只读模式、三个开关和附件文件夹。发送（enable_send）、永久删除（enable_destructive）和设置更改（enable_settings）默认关闭，除非你主动启用；只读模式不能与其中任何一项同时启用。此 MCP 服务不会在调用前征求任何人的许可。Claude Desktop 会对每个工具请求批准，可选择“允许一次”或“始终允许”；选择“始终允许”的工具之后会在未经询问的情况下运行，因此除非确实需要相应工具，否则请保持开关关闭。

该套件支持 macOS、Windows 和 Linux 的两种架构。其 SHA-256 值位于同一份经过签名的 checksums.txt 中。

该套件不会帮你登录。请同时安装二进制文件，运行一次 google-mail-mcp login --client-secret <your client JSON>，套件便会使用相同的凭据。

设置 Google

docs/gcp-setup.md 详细说明了完整流程：创建 Cloud 项目并启用 Gmail API、设置同意屏幕、选择与你运行 MCP 服务方式相对应的授权范围，并创建 桌面应用 OAuth 客户端。然后：

google-mail-mcp login --client-secret ~/path/to/client_secret.json
google-mail-mcp doctor

所有可读取邮件的 Gmail 授权范围都被 Google 列为受限范围。个人自用无需付费，但处于 Testing 状态的 External 客户端所获刷新令牌会在七天后过期；docs/runbook.md 说明了这种情况的表现。

通过 SSH 登录

回调会发送到远程主机的环回地址，而你的浏览器在本地，因此需要转发端口。运行 google-mail-mcp login --no-browser：它会打印授权 URL，以及所选端口对应的确切 ssh -L 命令。在第二个本地终端中运行该命令，然后在本地打开该 URL。

连接客户端

Claude Code：

claude mcp add google-mail -- google-mail-mcp

或者，在客户端配置文件中：

{
  "mcpServers": {
    "google-mail": {
      "command": "google-mail-mcp"
    }
  }
}

每项设置都是一个 GMAIL_* 环境变量，详见 docs/configuration.md。现在值得了解的设置有：GMAIL_READ_ONLY=true 只注册读取工具并申请只读权限；附件只能保存到 GMAIL_LOCAL_DIR 指定的目录；GMAIL_PROFILE 可让一台机器管理多个账户。

工具

工具	功能
get_profile	已登录的账号、账号统计数据和当前历史记录 ID
search_threads	使用 Gmail 搜索查找对话
search_messages	使用 Gmail 搜索查找单封邮件
get_thread	在预算范围内读取对话，按最新到最旧排列
get_message	通过 ID 或其 Message-ID 标头读取一封邮件
read_attachment	读取附件文本：纯文本、CSV、Markdown、JSON、HTML、日历或随附邮件
list_labels	列出所有标签，可选择显示数量
list_drafts	未发送的草稿
get_draft	读取一份草稿
list_changes	查看某个历史记录 ID 之后的变更，以及该游标何时过期
get_settings	转发、假期回复、代发地址、IMAP 和 POP，只读
list_filters	账号的过滤器，并标记出其中任何会转发邮件的过滤器
download_attachment	将附件保存到 GMAIL_LOCAL_DIR，绝不覆盖已有文件；仅在设置该变量时可用
download_attachments	以相同方式保存一封邮件的多个或全部附件；仅在设置 GMAIL_LOCAL_DIR 时可用
create_draft	保存新草稿、由服务端串入对话线程并可按需引用原邮件的回复，或附上原邮件的转发；不会发送任何邮件
update_draft	仅更改给定字段；如果草稿自读取后发生变化，则拒绝修改
delete_draft	永久删除草稿，需用其所包含的邮件命名，并设置 confirm: true
modify_labels	为最多 100 封邮件或对话添加或移除标签，并逐项报告
trash	将最多 100 封邮件或对话移至垃圾箱，保留 30 天
restore	将邮件或对话移出垃圾箱
create_label	创建用户标签
update_label	重命名用户标签或更改其显示方式
send_draft	发送草稿，需指定所有收件人、主题和首行；仅在 GMAIL_ENABLE_SEND=true 时可用
delete_permanently	永久删除最多 100 封邮件或对话，并设置 confirm: true；仅在 GMAIL_ENABLE_DESTRUCTIVE=true 时可用
delete_label	删除用户标签，并设置 confirm: true；仅在 GMAIL_ENABLE_DESTRUCTIVE=true 时可用
update_signature	设置账号某个地址的签名；仅在 GMAIL_ENABLE_SETTINGS=true 时可用
create_filter	为今后收到的邮件创建过滤器；不能转发或移至垃圾箱；仅在 GMAIL_ENABLE_SETTINGS=true 时可用
create_trash_filter	创建过滤器，在邮件到达时将符合条件的邮件移至垃圾箱，并设置 confirm: true；仅在 GMAIL_ENABLE_SETTINGS=true 和 GMAIL_ENABLE_DESTRUCTIVE=true 时可用
delete_filter	删除过滤器，需指定其条件，并设置 confirm: true；仅在 GMAIL_ENABLE_SETTINGS=true 和 GMAIL_ENABLE_DESTRUCTIVE=true 时可用
set_vacation	为联系人或网域开启假期回复，或将其关闭；仅在 GMAIL_ENABLE_SETTINGS=true 和 GMAIL_ENABLE_SEND=true 时可用

搜索在 q 中使用 Gmail 自身的搜索语法，并接受表示实际时刻的 after 和 before — Gmail 会将写在 q 中的日期视为太平洋时间午夜。每个结果都会说明消耗的配额。每项写入操作都会接受 dry_run，按 ID 指明操作对象，并根据 Gmail 的响应说明所做的更改。设置 GMAIL_READ_ONLY=true 会禁用写入操作。只有启用相应设置后，最后八个工具才会注册。

对于采用附件方式而非调用工具的客户端，gmail://threads/{id}、 gmail://messages/{id} 和 gmail://labels 提供的文本与 get_thread、get_message 和 list_labels 相同。

安全

• 邮件是数据。 邮件到达时会带有标记，隐藏内容会被移除并计数，而且没有任何工具描述会指示模型对邮件采取操作。

• 默认不会向其他人发送任何内容。 草稿会留在 Gmail 中等待发送，默认情况下没有工具会更改设置。转发设置只会显示，不会设置。

• 设置需主动启用。 设置 GMAIL_ENABLE_SETTINGS=true 后，服务可以设置签名并创建过滤器。过滤器不能转发邮件。将邮件移至垃圾箱的过滤器使用独立工具 create_trash_filter，它和 delete_filter 还需要 GMAIL_ENABLE_DESTRUCTIVE=true 和 confirm: true。假期回复会向其他人回复，因此也需要 GMAIL_ENABLE_SEND=true；它只会回复联系人或账号所在的网域，启用时还需要 confirm: true。

• 发送需主动启用，并通过草稿进行。 设置 GMAIL_ENABLE_SEND=true 后，send_draft 会按草稿中存储的内容原样发送。所有收件人（包括该对话中的参与者）都必须列在 confirm_recipients 中，调用还会附带草稿的主题和首行，因此客户端的提示词会显示将发送的内容；如果 Gmail 未确认发送成功，就绝不会重复发送。

• 移除操作会移至垃圾箱。 Gmail 会将移至垃圾箱的邮件保留 30 天，restore 可以将其恢复。默认情况下，唯一的永久移除操作是 delete_draft，它需要草稿所包含的邮件，并且需要 confirm: true。只有在设置 GMAIL_ENABLE_DESTRUCTIVE=true 后，才会启用 delete_permanently 和 delete_label；这也会请求唯一能够执行删除操作的权限范围。每次调用都需要 confirm: true。

• 每次调用都由客户端审批。 服务本身不会询问你。claude.ai 和 Codex 会在调用标记为破坏性的工具前显示提示：也就是所有会发送内容、更改设置或无法撤销的写入操作。VS Code 会在每次调用会写入数据的工具前显示提示。在 Claude Code 中，无论你的规则如何，delete_permanently 和 delete_label 每次调用都会询问，因为永久删除的邮件会跳过垃圾箱，而且移除标签会影响每封邮件。对于其他操作，请在设置的 permissions.ask 下逐一列出你想审批的调用，并用你为服务指定的名称替换 google-mail。例如，要审批会发送内容、更改设置或删除数据的写入操作：

  {
    "permissions": {
      "ask": [
        "mcp__google-mail__send_draft", "mcp__google-mail__set_vacation",
        "mcp__google-mail__update_signature", "mcp__google-mail__create_filter",
        "mcp__google-mail__create_trash_filter", "mcp__google-mail__delete_filter",
        "mcp__google-mail__delete_draft", "mcp__google-mail__delete_permanently",
        "mcp__google-mail__delete_label"
      ]
    }
  }
  

  无人监控的客户端可以执行所有已注册的写入操作，因此请先保持 GMAIL_ENABLE_SEND、GMAIL_ENABLE_DESTRUCTIVE 和 GMAIL_ENABLE_SETTINGS 关闭。

• 文件只会写入一个目录。 download_attachment 和 download_attachments 只会将文件写入 GMAIL_LOCAL_DIR，使用经过安全处理的文件名，并且绝不会覆盖现有文件。

• 日志绝不包含邮件内容。 日志中不会出现地址、主题、正文、标签名称或查询内容；ID 会截断为 6 个字符。测试会使用标记值驱动每个工具，如果任何值进入日志就会失败，因此调试日志可以安全地粘贴出来。

以上所有措施（客户端提示除外）都由服务强制执行。工具注解虽已设置，但只是提示，客户端可能会忽略。

docs/security.md 包含完整说明。

获取帮助

先运行 google-mail-mcp doctor：它会检查客户端 JSON、令牌、已授予的权限范围以及 Gmail API 是否已启用，并指出缺少的项目。docs/runbook.md 介绍常见问题。然后提交 issue，并附上 doctor 的输出和版本号。不要粘贴工具结果：它们就是邮件，包含他人的文字和地址。

版本管理

遵循语义化版本规范。工具名称及其输出字段是公开契约；CHANGELOG.md 会将需要你采取行动的变更标记为 Breaking。

开发

make check

CI 会运行这些内容。docs/development.md 说明了每个检查关卡的作用，以及实时驱动程序的工作方式。

文档

docs/README.md 是索引。设计、背后的平台事实，以及对每个 Gmail API 方法的评估，都收录在 docs/architecture.md 中。

贡献

请参阅 CONTRIBUTING.md。

安全

请通过私人安全公告报告漏洞；详情请参阅 SECURITY.md。

行为准则

CODE_OF_CONDUCT.md。

许可证

Apache 2.0。