Gmail MCP

Gmail MCP

English | Русский

A1 Gmail MCP 让 AI 应用能够用日常语言处理你的 Gmail 邮箱。搜索和阅读邮件、将回复准备为草稿、在准备好后发送、整理标签，并使用垃圾箱而非永久删除。

它通过你的 Google 账号使用 Gmail API。它会区分仍可编辑的草稿和无法撤回的已发送邮件，并明确说明 Gmail API 的限制，而不是暗示所有邮件操作都可撤销。

• 24 个工具。 搜索和阅读邮件与会话、直接发送邮件或通过草稿发送、管理草稿生命周期、标签和垃圾箱。
• 在对话中连接。 说“连接 Gmail”：服务会引导你完成 OAuth 客户端设置，使用 PKCE 在 127.0.0.1 接收 Google 的重定向，并自行保管令牌——无需配置文件，也无需重启。
• 谨慎发送。 草稿 → 审阅 → 发送是核心流程；发送会标记为破坏性操作，遇到结果不明确的失败时，服务绝不会重新发送——邮件无法撤回。
• 垃圾箱是安全保障。 移除邮件会将其移入可恢复的垃圾箱（约 30 天）；我们有意不提供永久删除邮件的工具。
• 有界读取。 解码后的邮件正文会截断到明确设定的限制，附件则以元数据形式返回，因此长篇新闻邮件不会悄然塞满对话。
• 最小化 Google 权限范围。 仅使用 gmail.modify——不会永久删除邮件，也无法访问 Gmail 设置。

从只读问题开始：

显示我过去一周未读的邮件，并告诉我哪些需要回复。

连接服务 · 探索使用场景 · 查看技术文档

一分钟了解其工作方式

你： 我收件箱里本周有哪些关于 Acme 合同的未读邮件？

助手： 使用 Gmail 查询语法进行搜索，并显示发件人、主题、日期和摘要。不会更改任何内容。

你： 给最新的一封邮件起草回复：我们会在周五发送签署后的副本。

助手： 在同一会话中创建草稿并显示出来供审阅。不会发送任何内容。

你： 发送。

助手： 发送草稿。发送是单独的、明确的破坏性步骤，因此你的 AI 应用可以先请求确认。

目录

• 快速开始
• 可以让它做什么
• 邮件如何变更
• 哪些内容可以变更
• 获取访问权限
• 配置
• 数据、限制和后台工作
• 技术文档
• 支持

快速开始

你需要 Node.js 20+ 和一个 Google 账号。安装时无需凭据——服务会在对话期间连接。

1. 将该服务添加到你的 AI 应用。
2. 说“连接 Gmail”：助手会引导你创建 OAuth 客户端并批准访问，无需编辑配置文件。
3. 提出上面那个只读问题。

codex mcp add google-gmail \
  -- npx -y mcp-google-gmail@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-gmail \
  -- npx -y mcp-google-gmail@latest

claude mcp list

{
  "mcpServers": {
    "google-gmail": {
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

{
  "servers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

可以让它做什么

整理收件箱

• 显示过去七天的未读邮件，并按发件人分组。
• 找到与 Acme 讨论合同的邮件会话，并按从早到晚的顺序总结。
• 哪些邮件有附件等着我处理？显示主题和文件名。

撰写并发送邮件

• 在此邮件会话中起草一封回复，说明签署后的副本会在周五发出。
• 把草稿给我看看，精简措辞，然后发送。
• 给团队发送一封简短的状态邮件，并将经理抄送。

保持邮箱井然有序

• 创建标签 Receipts/2026，并应用到匹配的邮件。
• 将本周的新闻邮件标记为已读并归档。
• 将该邮件会话移至垃圾箱——如果我改变主意，再恢复它。

邮件会发生哪些变化

1. 安全的发送方式是先创建草稿：create_draft 准备邮件，get_draft 显示邮件以供审核，send_draft 发送邮件。send_message 会跳过草稿，立即发送。
2. 已发送的邮件无法从外部撤回。超时或出现 5xx 错误后，服务端不会重新发送；再次尝试前请搜索 in:sent，因为重放发送操作会导致邮件被发送两次。
3. 移除邮件或邮件会话意味着将其移至垃圾箱。manage_trash 可在约 30 天内撤销；我们有意不提供永久删除工具。
4. 草稿是个例外：update_draft 会替换整个草稿（API 不支持部分编辑），而 delete_draft 会永久删除草稿，因为草稿不会经过垃圾箱。

每次调用只针对一个邮箱——即授予令牌的账号。解码后的正文会按可配置的上限截断，并明确标记；附件只返回元数据，附件内容则有意通过 raw_request 获取。

可以进行哪些更改

AI 客户端控制确认提示。服务会为读取、写入和破坏性工具添加标记，以便客户端区分检查操作和实际更改。

获取访问权限

Google Gmail 需要 OAuth 2.0；仅有 API 密钥并不足够。有两种接入方式，第一种无需配置文件。

从聊天中连接（推荐）

说“connect Gmail”，助手就会引导你完成流程：

1. setup_instructions 会打印检查清单：创建或选择 Google Cloud 项目，启用 Gmail API，配置同意屏幕并创建 Desktop app OAuth 客户端。
2. 下载该客户端的 JSON（“Download JSON”），并将其路径提供给助手——set_client 会以仅所有者可访问的权限保存该文件。密钥不会经过对话。
3. start_login 会返回 Google 授权链接。在此机器上打开链接并批准；授权码会返回到 127.0.0.1 上的一次性监听器（PKCE），不会经过聊天。
4. finish_login 会交换授权码，并将令牌保存到 ~/.config/mcp-google-gmail/credentials.json（模式为 0600），再通过一次真实的 Gmail API 调用进行验证——如果 API 仍处于关闭状态，会立即发现。

每次调用都会重新读取令牌，因此连接会立即生效，无需重启 AI 应用。auth_status 会显示已连接的内容，logout 会撤销并删除连接。

环境变量（CI、无人值守安装）

1. 创建或选择一个 Google Cloud 项目，并启用 Gmail API。

2. 配置 OAuth 同意屏幕，并创建 Desktop app OAuth 客户端。

3. 授权要连接其邮箱的 Google 账号——每次调用都只会操作该邮箱。OAuth 2.0 Playground 可以在启用 Use your own OAuth credentials 后获取刷新令牌。

4. 请求以下范围：

   https://www.googleapis.com/auth/gmail.modify
   

   它涵盖搜索、读取、发送、草稿、标签和移至垃圾箱，但不包括永久删除和 Gmail 设置。通过 raw_request 永久删除邮件，还需要完整的 https://mail.google.com/ 范围。

测试模式下的 OAuth 刷新令牌可能会在 7 天后过期。需要长期访问时，请发布 OAuth 应用，或在 Workspace 网域中使用 Internal 应用。请将客户端密钥和刷新令牌视为密码。

配置

所有变量都是可选的——即使不设置任何变量，服务也会从聊天中连接。

* 提供 OAuth 三项配置，或访问令牌。

数据、限制和后台工作

• 请求会发送至 Gmail。 本地服务会刷新 Google OAuth 令牌并调用 Gmail API。其匿名遥测数据包含安装 ID、软件包版本、AI 客户端和平台版本，以及工具名称——绝不包含 OAuth 令牌、邮件内容、工具参数或提示词。设置 ASKADS_TELEMETRY=0 即可选择退出。
• Google 会按配额单位计量。 Gmail 每位用户每秒大约允许 250 个配额单位；发送邮件消耗 100 个单位，典型的读取操作消耗 5 个。个人账号每天可发送约 500 封邮件，Workspace 账号约 2,000 封。遇到 429 时，服务会采用退避策略；读取操作在网络错误和 5xx 错误后也会重试，而发送及其他写入操作在失败情况不确定时绝不会重放。
• 没有后台轮询。 服务仅在被调用时运行。如果你的 AI 应用支持定时任务，就可以定期检查收件箱；raw_request 也可以调用 history.list 进行增量同步。

技术文档

• MCP 功能目录 — 面向任务的页面，涵盖每个工具。
• 全部工具和输入
• 开发文档
• 发布文档
• Gmail API 参考

支持

发现 Bug 或有使用场景需求？创建 Issue，或在 Telegram 上联系我们。

你已读到最后！