Gmail MCP Server

Gmail MCP Server（积极维护的分支）

安装： npx @artymclabin/gmail-mcp auth——或者直接让 Claude 从此仓库安装 MCP（https://github.com/ArtyMcLabin/Gmail-MCP-Server），并完成设置。想手动操作？请参阅安装与身份验证。

也可在官方 MCP Registry（io.github.ArtyMcLabin/Gmail-MCP-Server）和 Smithery 上找到。

这是 GongRzhe/Gmail-MCP-Server 的一个积极维护的分支。

原始仓库自 2025 年 8 月以来就无人维护——7 个多月没有维护者活动，还有 72 个以上未合并的拉取请求。我每天都会在 Claude Code 工作流中使用此 MCP 服务，并依赖它正常工作，所以我接手维护了。

欢迎提交拉取请求。 如果你一直保留着修复或功能，却找不到提交的地方，这里就是。

理念

此分支追求精简务实。它是一个本地 stdio MCP 服务——你在自己的机器上运行它，而你的大模型客户端已经可以访问 shell 和文件系统。因此，威胁模型是“不要向第三方泄露凭据，不要破坏 Gmail 的现有功能”，而不是“防御托管式多租户服务”。我尽量减少依赖。我每天都会在自己的 Claude Code 工作流中使用它——如果我自己都不愿意运行或维护某个功能，它就不会加入。

有一个下游分支选择了极致扩展的路线。我与其维护者没有关联，也不跟踪其安全状况或功能——请自行承担使用风险：klodr/gmail-mcp。如果这更符合你的理念，不妨去看看。这里一如既往地欢迎 PR。

此分支新增内容

• 修复回复线程 - 自动解析 In-Reply-To 和 References 标头，使邮件回复进入正确的线程，而不是创建无归属的邮件（上游 PR #91，仍在等待处理）
• 支持发件人别名 - 可选的 from 参数，用于管理多个邮件身份（可使用任意已配置的 Gmail 别名发送邮件）
• 回复全部工具 - reply_all 会自动获取原始邮件、构建 To/CC 收件人列表（排除你自己），并设置正确的线程标头（由 @MaxGhenis 提交的 PR #3）
• 修复 list_filters - 因响应属性名称错误而返回空数组（由 @nicholas-anthony-ai 提交的 PR #4）
• 自定义 OAuth2 作用域 - 使用 --scopes 标志仅申请所需权限，并自动筛选工具（由 @tansanDOTeth 提交的 PR #6）
• 强化 CI/CD 安全性 - 修复 GitHub Actions 工作流中的 Shell 注入漏洞，并添加最小权限范围（由 @JF10R 提交的 PR #9）
• 强化安全性 - 修复附件下载中的路径遍历问题，并限制 OAuth 凭据文件权限（由 @JF10R 提交的 PR #10）
• 依赖项安全性 - 将 MCP SDK 升级至 v1.27.1（修复 3 个 CVE），升级 nodemailer（修复 DoS 和路由问题），并将仅用于开发的包移出生产依赖项（由 @JF10R 提交的 PR #11）
• 线程级工具 - get_thread、list_inbox_threads、get_inbox_with_threads、modify_thread，可通过单次调用高效执行基于线程的邮件操作
• 显示 CC/BCC 信息 - read_email 现在会在存在 CC 和 BCC 标头时显示它们（由 @panghy 提交的 PR #21）
• 钓鱼邮件举报工具 - report_phishing 和 batch_report_phishing，可通过 Gmail API 将邮件标记为垃圾邮件（由 @ShivamB25 提交的 PR #24）
• 草稿生命周期工具 - send_draft、delete_draft、update_draft 弥补了草稿遗留问题：send_draft 会原子性地发送现有草稿并将其从草稿箱移除（不会留下幽灵副本）；update_draft 会原地修改草稿并保留其 ID（避免在迭代循环中堆积草稿）；delete_draft 会丢弃已放弃的草稿（由 @thisisambros 提交的 PR #30）
• 工具注解 - 在所有工具上添加 MCP 规范注解（readOnlyHint、destructiveHint、idempotentHint），让大模型更安全地执行工具（由 @bryankthompson 提交的 PR #14）
• 下载邮件工具 - download_email 可将邮件以 json/eml/txt/html 格式保存到磁盘，而不会占用大模型上下文（由 @icanhasjonas 提交的 PR #13）
• 持久化 OAuth 会话 - 重启后会保留 refresh_token，不再需要每小时重新进行身份验证（由 @BrentBaccala 提交的 PR #35）
• 自定义 OAuth 回调端口 - 身份验证监听器会根据你的回调 URL 获取端口和路径，而不再将端口硬编码为 3000（由 @soapergem 提交的 PR #41）
• 安全地限制永久删除操作 - delete_email/batch_delete_emails 需要选择启用 gmail.full 作用域（该作用域也满足所有其他邮件作用域），因此默认身份验证仍遵循最小权限原则（由 @caioribeiroclw-pixel 提交的 PR #39） 所有功能均已在日常使用中通过生产环境测试。

---

一个用于在 Claude Desktop 中集成 Gmail 并支持自动身份验证的模型上下文协议（MCP）服务。此服务可让 AI 助手通过自然语言交互管理 Gmail。

功能

• 发送包含主题、内容、附件和收件人的邮件
• 完整的附件支持——发送和接收文件附件
• 将邮件附件下载到本地文件系统
• 将完整邮件下载为 json/eml/txt/html 格式的文件
• 线程级操作——获取完整邮件线程、列出收件箱邮件线程、批量展开邮件线程
• 支持 HTML 邮件，以及同时包含 HTML 和纯文本版本的多部分消息
• 完整支持主题行和邮件内容中的国际字符
• 通过 ID 读取邮件，并高级处理 MIME 结构
• 增强的附件显示，展示文件名、类型、大小和下载 ID
• 根据各种条件（主题、发件人、日期范围）搜索邮件
• 全面的标签管理，可创建、更新、删除和列出标签
• 列出所有可用的 Gmail 标签（系统标签和用户定义的标签）
• 列出收件箱、已发送或自定义标签中的邮件
• 将邮件标记为已读/未读
• 将邮件移动到其他标签/文件夹
• 删除邮件
• 支持批量操作，高效地一次处理多封邮件
• 与 Gmail API 完全集成
• 简单的 OAuth2 身份验证流程，自动启动浏览器
• 支持桌面应用和 Web 应用凭据
• 全局凭据存储，方便使用

安装与身份验证

从 npm 安装（推荐）

npx @artymclabin/gmail-mcp auth

从源代码安装

git clone https://github.com/ArtyMcLabin/Gmail-MCP-Server.git
cd Gmail-MCP-Server
npm install
npm run build

注意：旧版文档中的 npx @gongrzhe/server-gmail-autoauth-mcp 命令指向已停止维护的上游分支。此分支以 @artymclabin/gmail-mcp 发布。

设置 Google Cloud 凭据

1. 创建 Google Cloud 项目并获取凭据：

   a. 创建 Google Cloud 项目：

   • 前往 Google Cloud 控制台
   • 创建新项目或选择现有项目
   • 为项目启用 Gmail API

   b. 创建 OAuth 2.0 凭据：

   • 前往“API 和服务” > “凭据”
   • 点击“创建凭据” > “OAuth 客户端 ID”
   • 将“桌面应用”或“Web 应用”选为应用类型
   • 为其命名，然后点击“创建”
   • 对于 Web 应用，请将 http://localhost:3000/oauth2callback 添加到获准的重定向 URI
   • 下载客户端 OAuth 密钥的 JSON 文件
   • 将密钥文件重命名为 gcp-oauth.keys.json

2. 运行身份验证：

   你可以通过两种方式进行身份验证：

   a. 全局身份验证（推荐）：

   # First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
   mkdir -p ~/.gmail-mcp
   mv gcp-oauth.keys.json ~/.gmail-mcp/
   
   # Run authentication from anywhere
   node dist/index.js auth
   

   b. 本地身份验证：

   # Place gcp-oauth.keys.json in your current directory
   # The file will be automatically copied to global config
   node dist/index.js auth
   

   身份验证过程将会：

   • 在当前目录或 ~/.gmail-mcp/ 中查找 gcp-oauth.keys.json
   • 如果该文件位于当前目录，则将其复制到 ~/.gmail-mcp/
   • 打开默认浏览器以进行 Google 身份验证
   • 将凭据保存为 ~/.gmail-mcp/credentials.json

   注意：

   • 成功完成身份验证后，凭据会全局存储在 ~/.gmail-mcp/ 中，可从任何目录使用
   • 支持“桌面应用”和“Web 应用”凭据
   • 对于 Web 应用凭据，请确保将 http://localhost:3000/oauth2callback 添加到获准的重定向 URI

   自定义回调 URL / 端口： 默认情况下，本地 OAuth 服务会在端口 3000 的 /oauth2callback 路径上侦听。如果端口 3000 不可用，或者你需要使用其他重定向 URI，请将完整回调 URL 作为参数传入。侦听器会自动绑定到该 URL 中的端口和路径：

   node dist/index.js auth http://localhost:8080/oauth2callback
   

   传入的 URL 必须与 Google Cloud 控制台中注册的某个获准重定向 URI 完全一致。

3. 在 Claude Desktop 中配置：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/absolute/path/to/Gmail-MCP-Server/dist/index.js"
      ]
    }
  }
}

Docker 支持

如果你更愿意使用 Docker：

1. 身份验证：

docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth

2. 使用：

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-gmail:/gmail-server",
        "-e",
        "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
        "mcp/gmail"
      ]
    }
  }
}

云服务端身份验证

对于云服务端环境（如 n8n），你可以在身份验证时指定自定义回调 URL：

node dist/index.js auth https://gmail.gongrzhe.com/oauth2callback

云环境设置说明

1. 配置反向代理：

   • 设置 n8n 容器以开放用于身份验证的端口
   • 配置反向代理，将来自你的域名（例如 gmail.gongrzhe.com）的流量转发到此端口

2. DNS 配置：

   • 在 DNS 设置中添加 A 记录，将你的域名解析到云服务端的 IP 地址

3. Google Cloud Platform 设置：

   • 在 Google Cloud 控制台中，将自定义域名回调 URL（例如 https://gmail.gongrzhe.com/oauth2callback）添加到获准的重定向 URI 列表

4. 运行身份验证：

   node dist/index.js auth https://gmail.gongrzhe.com/oauth2callback
   

5. 在应用程序中配置：

   {
     "mcpServers": {
       "gmail": {
         "command": "node",
         "args": [
           "/absolute/path/to/Gmail-MCP-Server/dist/index.js"
         ]
       }
     }
   }
   

这种方法可以让身份验证流程在无法访问 localhost 的环境中正常工作，例如容器化应用或云服务端。

OAuth 作用域

你可以在身份验证期间指定 OAuth 作用域，以限制服务对 Gmail 的访问权限。这可以控制大模型可用的工具，从而缩小敏感操作的攻击面。

可用作用域

作用域	描述
gmail.readonly	只读访问邮件（搜索、阅读、下载附件）
gmail.modify	完整的邮件读写访问权限（包含 readonly 的全部权限，并包括发送、修改和删除）
gmail.compose	仅创建草稿和发送邮件
gmail.send	仅发送邮件
gmail.labels	仅管理标签
gmail.settings.basic	管理过滤器和设置

注意：gmail.modify 包含所有读取权限。如果你已拥有 gmail.modify，则无需 gmail.readonly。

使用特定范围进行身份验证

使用 --scopes 标志仅申请所需的权限：

# Read-only access (recommended for safe browsing)
node dist/index.js auth --scopes=gmail.readonly

# Read-only with filter management
node dist/index.js auth --scopes=gmail.readonly,gmail.settings.basic

# Full access (default behavior)
node dist/index.js auth --scopes=gmail.modify,gmail.settings.basic

如果未提供 --scopes 标志，服务将默认使用 gmail.modify,gmail.settings.basic，以提供完整功能。

范围与工具的映射

服务会根据已授权的范围自动筛选可用工具：

工具	所需范围（任一）
read_email、search_emails、download_attachment	gmail.readonly 或 gmail.modify
list_email_labels	gmail.readonly、gmail.modify 或 gmail.labels
send_email、draft_email、reply_all、send_draft	gmail.modify、gmail.compose 或 gmail.send
delete_draft、update_draft	gmail.modify 或 gmail.compose
modify_email、batch_modify_emails、modify_thread、report_phishing、batch_report_phishing	gmail.modify
delete_email、batch_delete_emails	gmail.full（https://mail.google.com/）
create_label、update_label、delete_label、get_or_create_label	gmail.modify 或 gmail.labels
list_filters、get_filter、create_filter、delete_filter、create_filter_from_template	gmail.settings.basic

gmail.full 有意与默认范围分开，因为它授予永久删除权限。对于归档、标记为已读、添加标签或清理收件箱等操作，优先使用 modify_email / batch_modify_emails；仅当助手需要永久删除邮件时，才使用 --scopes=gmail.full,gmail.settings.basic 重新进行身份验证。gmail.full 包含其他邮件范围，因此这一组合会保留所有读取、发送、修改和标签工具的可用性（设置范围仍然单独处理——Gmail 的过滤器端点只接受 gmail.settings.*）。

重新进行身份验证

要更改范围，只需使用不同的范围再次运行身份验证命令。这将替换现有凭据。

Claude Code CLI 配置

要将此 MCP 服务与 Claude Code 配合使用，请将其添加到 MCP 设置中。

只读配置（安全浏览推荐）

首先，使用只读范围进行身份验证：

node dist/index.js auth --scopes=gmail.readonly

然后将其添加到 Claude Code MCP 设置中（~/.claude/mcp_settings.json 或项目级 .mcp.json）：

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["/absolute/path/to/Gmail-MCP-Server/dist/index.js"]
    }
  }
}

使用只读范围时，Claude 只能使用以下 4 个工具：

• read_email - 阅读邮件内容
• search_emails - 搜索收件箱
• list_email_labels - 列出可用标签
• download_attachment - 下载附件

完整访问权限配置

要使用完整的 Gmail 管理功能：

node dist/index.js auth --scopes=gmail.modify,gmail.settings.basic

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["/absolute/path/to/Gmail-MCP-Server/dist/index.js"]
    }
  }
}

这将启用全部 23 个工具，包括发送邮件、管理标签、创建过滤器、回复所有人、线程操作、钓鱼邮件举报和批量操作。

运行多个实例（工具名称前缀）

一些 MCP 客户端会根据工具的基础名称对不同服务中的工具条目去重，这使得无法并行运行此服务的两个实例（例如，一个用于个人账号，另一个用于共享收件箱）——即使两个服务都显示为已连接，也只会显示其中一个实例的工具。

服务接受可选的 --tool-prefix=<value> CLI 标志（或 GMAIL_MCP_TOOL_PREFIX 环境变量），用于在注册时为每个工具名称添加前缀。默认值为空（完全向后兼容）。

示例：在 Claude Code 中使用不同前缀注册两个实例：

# Personal account
claude mcp add gmail-personal -s user \
  -e GMAIL_CREDENTIALS_PATH=$HOME/.gmail-mcp/credentials-personal.json \
  -- node /absolute/path/to/Gmail-MCP-Server/dist/index.js --tool-prefix=personal_

# Shared inbox
claude mcp add gmail-info -s user \
  -- node /absolute/path/to/Gmail-MCP-Server/dist/index.js --tool-prefix=info_

随后，工具会显示为 mcp__gmail-personal__personal_search_emails、mcp__gmail-info__info_search_emails 等，各层级的名称都各不相同。分发处理程序会移除前缀，并通过 getToolByName 查找解析后的名称；只有当结果是已知工具时才会移除前缀（因此，即使前缀值与真实工具名称重叠，也不会导致静默的错误分发）。

auth 子命令会在服务启动前运行，不受影响——调用时不要使用 --tool-prefix。

可用工具

服务提供以下工具，可通过 Claude Desktop 使用：

1. 发送邮件（send_email）

立即发送新邮件。支持纯文本、HTML 或多部分邮件，可选添加文件附件和内嵌图片。

基本邮件：

{
  "to": ["[email protected]"],
  "subject": "Meeting Tomorrow",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "cc": ["[email protected]"],
  "bcc": ["[email protected]"],
  "mimeType": "text/plain"
}

包含附件的邮件：

{
  "to": ["[email protected]"],
  "subject": "Project Files",
  "body": "Hi,\n\nPlease find the project files attached.\n\nBest regards",
  "attachments": [
    "/path/to/document.pdf",
    "/path/to/spreadsheet.xlsx",
    "/path/to/presentation.pptx"
  ]
}

HTML 邮件示例：

{
  "to": ["[email protected]"],
  "subject": "Meeting Tomorrow",
  "mimeType": "text/html",
  "body": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

多部分邮件示例（HTML + 纯文本）：

{
  "to": ["[email protected]"],
  "subject": "Meeting Tomorrow",
  "mimeType": "multipart/alternative",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "htmlBody": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

内嵌图片（嵌入 HTML 中）：

将图片嵌入 HTML 正文，使其显示在正文对应位置，而不是作为单独附件发送。通过图片的 cid 在 htmlBody 中引用，并以文件 path 或 base64 content 的形式提供图片。draft_email、update_draft 和 reply_all 也支持相同用法。

{
  "to": ["[email protected]"],
  "subject": "Quarterly Report",
  "body": "Revenue is up. See the chart below.",
  "htmlBody": "<p>Revenue is up:</p><img src=\"cid:chart1\">",
  "inlineImages": [
    { "cid": "chart1", "path": "/path/to/chart.png" }
  ]
}

2. 草稿邮件（draft_email）

创建邮件草稿，但不发送。同样支持附件。

{
  "to": ["[email protected]"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["[email protected]"],
  "attachments": ["/path/to/draft_report.docx"]
}

3. 读取邮件（read_email）

按邮件 ID 获取指定邮件的内容。现在会显示增强的附件信息。

{
  "messageId": "182ab45cd67ef"
}

增强响应会包含 CC/BCC 标头（如有）和附件详情：

Subject: Project Files
From: [email protected]
To: [email protected]
CC: [email protected]
Date: Thu, 19 Jun 2025 10:30:00 -0400

Email body content here...

Attachments (2):
- document.pdf (application/pdf, 245 KB, ID: ANGjdJ9fkTs-i3GCQo5o97f_itG...)
- spreadsheet.xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 89 KB, ID: BWHkeL8gkUt-j4HDRp6o98g_juI...)

4. 下载附件（download_attachment）

新增：将邮件附件下载到本地文件系统。

{
  "messageId": "182ab45cd67ef",
  "attachmentId": "ANGjdJ9fkTs-i3GCQo5o97f_itG...",
  "savePath": "/path/to/downloads",
  "filename": "downloaded_document.pdf"
}

参数：

• messageId：包含该附件的邮件 ID
• attachmentId：附件 ID（显示在增强的邮件信息中）
• savePath：保存文件的目录（可选，默认使用当前目录）
• filename：自定义文件名（可选；未提供时使用原始文件名）

5. 搜索邮件（search_emails）

使用 Gmail 搜索语法搜索邮件。

{
  "query": "from:[email protected] after:2024/01/01 has:attachment",
  "maxResults": 10
}

6. 修改邮件（modify_email）

为邮件添加或移除标签（移动到其他文件夹、归档等）。

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

7. 删除邮件（delete_email）

永久删除邮件。此工具需要 gmail.full（https://mail.google.com/）；默认的 gmail.modify 范围不足以调用 Gmail 的永久删除端点。

{
  "messageId": "182ab45cd67ef"
}

8. 列出邮件标签（list_email_labels）

获取所有可用的 Gmail 标签。

{}

9. 创建标签（create_label）

创建新的 Gmail 标签。

{
  "name": "Important Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10. 更新标签（update_label）

更新现有 Gmail 标签。

{
  "id": "Label_1234567890",
  "name": "Urgent Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

11. 删除标签（delete_label）

删除 Gmail 标签。

{
  "id": "Label_1234567890"
}

12. 获取或创建标签（get_or_create_label）

按名称获取现有标签；如果不存在，则创建该标签。

{
  "name": "Project XYZ",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

13. 批量修改邮件（batch_modify_emails）

通过高效的批处理修改多封邮件的标签。

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"],
  "batchSize": 50
}

14. 批量删除邮件（batch_delete_emails）

通过高效的批处理永久删除多封邮件。此工具需要 gmail.full（https://mail.google.com/）；默认的 gmail.modify 范围不足以调用 Gmail 的永久删除端点。

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

15. 创建过滤器（create_filter）

根据自定义条件和操作创建新的 Gmail 过滤器。

{
  "criteria": {
    "from": "[email protected]",
    "hasAttachment": false
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

16. 列出过滤器（list_filters）

获取所有 Gmail 过滤器。

{}

17. 获取过滤器（get_filter）

获取指定 Gmail 过滤器的详情。

{
  "filterId": "ANe1Bmj1234567890"
}

18. 删除过滤器（delete_filter）

删除 Gmail 过滤器。

{
  "filterId": "ANe1Bmj1234567890"
}

19. 根据模板创建过滤器（create_filter_from_template）

使用针对常见场景的预定义模板创建过滤器。

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "[email protected]",
    "labelIds": ["Label_GitHub"],
    "archive": true
  }
}

20. 全部回复（reply_all）

向邮件的所有收件人回复。自动获取原始邮件以构建收件人列表，并设置正确的线程标头（In-Reply-To、References、threadId）。

工作原理：

1. 根据 messageId 获取原始邮件
2. 根据原始发件人（From 标头）构建 To
3. 根据原始 To 和 CC 构建 CC，并排除您自己的邮箱
4. 设置线程标头，确保回复进入正确的邮件线程
5. 通过现有的 send_email 流程发送（支持附件、HTML 和 multipart）

{
  "messageId": "182ab45cd67ef",
  "body": "Thanks for the update, everyone. I'll review and get back to you.",
  "mimeType": "text/plain"
}

使用 HTML 和附件：

{
  "messageId": "182ab45cd67ef",
  "body": "Plain text fallback",
  "htmlBody": "<p>Thanks for the update. See attached notes.</p>",
  "mimeType": "multipart/alternative",
  "attachments": ["/path/to/notes.pdf"]
}

参数：

• messageId（必需）：要回复的邮件 ID
• body（必需）：回复正文（纯文本；使用 multipart 时也可作为回退内容）
• htmlBody（可选）：回复正文的 HTML 版本
• mimeType（可选）：text/plain（默认）、text/html 或 multipart/alternative
• attachments（可选）：要附加的文件路径数组

21. 修改线程（modify_thread）

以原子方式修改整个线程（一次性修改所有邮件）的标签。解决了仅归档最新邮件会导致较早邮件仍留在收件箱的问题。

{
  "threadId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

22. 举报网络钓鱼（report_phishing）

通过应用 SPAM 标签，使用最接近的公开 Gmail API 行为将邮件举报为网络钓鱼。

{
  "messageId": "182ab45cd67ef"
}

注意：Gmail API 不提供完整的原生“举报网络钓鱼”流程。此工具会应用 SPAM 标签，作为最接近的可用替代方案。

23. 批量举报网络钓鱼（batch_report_phishing）

以高效的批次将多封邮件举报为网络钓鱼。

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

24. 发送草稿（send_draft）

通过 users.drafts.send 原子地发送现有草稿，并在同一操作中将其从草稿箱中移除，不会留下孤立或残留的草稿。draft_email（或 update_draft）确认内容后即可使用。

{
  "draftId": "r-1234567890123456789"
}

25. 更新草稿（update_draft）

通过 users.drafts.update 就地替换草稿内容，保留草稿 ID。这对迭代流程（草稿 → 用户请求修改 → 重新起草）至关重要，可避免草稿箱中累积 N 个副本。此工具复用与 draft_email 相同的 MIME 构建器，因此附件和线程语义保持一致。

{
  "draftId": "r-1234567890123456789",
  "to": ["[email protected]"],
  "subject": "Revised Report",
  "body": "Updated draft content.",
  "cc": ["[email protected]"],
  "attachments": ["/path/to/report.docx"]
}

26. 删除草稿（delete_draft）

通过 users.drafts.delete 丢弃已放弃的草稿。

{
  "draftId": "r-1234567890123456789"
}

规范的草稿生命周期

draft_email(...) → draftId
  ↓ (user wants changes)
update_draft(draftId, ...)   // mutate in place, same ID
  ↓ (user confirms)
send_draft(draftId)          // atomic send + draft removal

或者中止：delete_draft(draftId)。

过滤器管理功能

过滤条件

您可以根据各种条件创建过滤器：

条件	示例	描述
from	"[email protected]"	来自特定发件人的邮件
to	"[email protected]"	发给特定收件人的邮件
subject	"Meeting"	主题中包含特定文本的邮件
query	"has:attachment"	Gmail 搜索查询语法
negatedQuery	"spam"	不得包含的文本
hasAttachment	true	带有附件的邮件
size	10485760	邮件大小，单位为字节
sizeComparison	"larger"	大小比较（larger、smaller）

过滤器操作

过滤器可以执行以下操作：

操作	示例	描述
addLabelIds	["IMPORTANT", "Label_Work"]	为匹配的邮件添加标签
removeLabelIds	["INBOX", "UNREAD"]	移除匹配邮件的标签
forward	"[email protected]"	将邮件转发到其他地址

过滤器模板

服务包含适用于常见过滤场景的预置模板：

1. 按发件人筛选模板（fromSender）

筛选来自特定发件人的邮件，并可选择将其归档。

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "[email protected]",
    "labelIds": ["Label_Newsletter"],
    "archive": true
  }
}

2. 按主题筛选模板（withSubject）

筛选主题包含特定文本的邮件，并可选择将其标记为已读。

{
  "template": "withSubject",
  "parameters": {
    "subjectText": "[URGENT]",
    "labelIds": ["Label_Urgent"],
    "markAsRead": false
  }
}

3. 附件筛选模板（withAttachments）

筛选所有带有附件的邮件。

{
  "template": "withAttachments",
  "parameters": {
    "labelIds": ["Label_Attachments"]
  }
}

4. 大邮件模板（largeEmails）

筛选大小超过指定值的邮件。

{
  "template": "largeEmails",
  "parameters": {
    "sizeInBytes": 10485760,
    "labelIds": ["Label_Large"]
  }
}

5. 内容筛选模板（containingText）

筛选包含特定文本的邮件，并可选择将其标记为重要邮件。

{
  "template": "containingText",
  "parameters": {
    "searchText": "invoice",
    "labelIds": ["Label_Finance"],
    "markImportant": true
  }
}

6. 邮件列表模板（mailingList）

筛选邮件列表邮件，并可选择将其归档。

{
  "template": "mailingList",
  "parameters": {
    "listIdentifier": "dev-team",
    "labelIds": ["Label_DevTeam"],
    "archive": true
  }
}

常见筛选示例

以下是一些实用的筛选示例：

自动整理新闻邮件：

{
  "criteria": {
    "from": "[email protected]"
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

处理促销邮件：

{
  "criteria": {
    "query": "unsubscribe OR promotional"
  },
  "action": {
    "addLabelIds": ["Label_Promotions"],
    "removeLabelIds": ["INBOX", "UNREAD"]
  }
}

来自老板的优先邮件：

{
  "criteria": {
    "from": "[email protected]"
  },
  "action": {
    "addLabelIds": ["IMPORTANT", "Label_Boss"]
  }
}

大型附件：

{
  "criteria": {
    "size": 10485760,
    "sizeComparison": "larger",
    "hasAttachment": true
  },
  "action": {
    "addLabelIds": ["Label_LargeFiles"]
  }
}

高级搜索语法

search_emails 工具支持 Gmail 强大的搜索运算符：

运算符	示例	说明
from:	from:[email protected]	来自特定发件人的邮件
to:	to:[email protected]	发给特定收件人的邮件
subject:	subject:"meeting notes"	主题中包含特定文本的邮件
has:attachment	has:attachment	带附件的邮件
after:	after:2024/01/01	在某个日期之后收到的邮件
before:	before:2024/02/01	在某个日期之前收到的邮件
is:	is:unread	具有特定状态的邮件
label:	label:work	带有特定标签的邮件

你可以组合多个运算符：from:[email protected] after:2024/01/01 has:attachment

高级功能

电子邮件附件支持

该服务提供全面的附件功能：

• 发送附件：发送邮件或撰写邮件时，在 attachments 数组中包含文件路径
• 附件检测：自动检测 MIME 类型和文件大小
• 下载功能：将任意邮件附件下载到本地文件系统
• 增强显示：查看详细的附件信息，包括文件名、类型、大小和下载 ID
• 多种格式：支持所有常见文件类型（文档、图像、压缩文件等）
• 符合 RFC822：使用 Nodemailer 正确格式化 MIME 消息

支持的文件类型：所有标准文件类型，包括 PDF、DOCX、XLSX、PPTX、图像（PNG、JPG、GIF）、压缩文件（ZIP、RAR）等。

邮件内容提取

该服务可以智能地从复杂的 MIME 结构中提取邮件内容：

• 优先使用纯文本内容（如果可用）
• 如果没有纯文本内容，则使用 HTML 内容
• 处理带有嵌套部分的多部分 MIME 消息
• 处理附件信息（文件名、类型、大小、下载 ID）
• 保留原始邮件标头（From、To、Subject、Date）

国际字符支持

该服务全面支持邮件主题和内容中的非 ASCII 字符，包括：

• 土耳其语、中文、日语、韩语及其他非拉丁字母文字
• 特殊字符和符号
• 通过正确编码确保在邮件客户端中正确显示

全面的标签管理

该服务提供一整套 Gmail 标签管理工具：

• 创建标签：创建新的标签并自定义可见性设置
• 更新标签：重命名标签或更改其可见性设置
• 删除标签：移除用户创建的标签（系统标签受到保护）
• 查找或创建：按名称获取标签，或在找不到时自动创建
• 列出所有标签：查看所有系统和用户标签及其详细信息
• 标签可见性选项：控制标签在邮件列表和标签列表中的显示方式

标签可见性设置包括：

• messageListVisibility：控制标签是否显示在邮件列表中（show 或 hide）
• labelListVisibility：控制标签在标签列表中的显示方式（labelShow、labelShowIfUnread 或 labelHide）

这些标签管理功能让你可以直接通过 Claude 精细整理邮件，无需切换到 Gmail 界面。

批量操作

服务器具备高效的批处理能力：

• 一次处理最多 50 封邮件（批次大小可配置）
• 自动拆分大型邮件集，避免触及 API 限制
• 为每项操作详细报告成功或失败情况
• 发生错误时优雅处理，并单独重试
• 非常适合批量管理收件箱和整理任务

安全说明

• OAuth 凭据安全地存储在本地环境中（~/.gmail-mcp/）
• 服务器使用离线访问，以保持持久身份验证
• 切勿分享凭据或将其提交到版本控制系统
• 定期在 Google 帐户设置中检查并撤销未使用的访问权限
• 凭据全局存储，但只有当前用户可以访问
• 附件文件在本地处理，服务器不会永久存储这些文件

故障排除

1. 未找到 OAuth 密钥

   • 确保 gcp-oauth.keys.json 位于当前目录或 ~/.gmail-mcp/ 中
   • 检查文件权限

2. 凭据格式无效

   • 确保 OAuth 密钥文件包含 web 或 installed 凭据
   • 对于 Web 应用，请确认重定向 URI 配置正确

3. 端口已被占用

   • 默认情况下，身份验证使用端口 3000；运行身份验证前请释放该端口，或者传入自定义回调 URL，在其他端口运行（例如 node dist/index.js auth http://localhost:8080/oauth2callback）
   • 如果要释放端口 3000，可以查找并停止占用该端口的进程
   • 自定义回调 URL 必须与 Google Cloud Console 中注册的某个已获授权重定向 URI 匹配

4. 批量操作失败

   • 批量操作失败时，会自动重试各个项目
   • 查看详细错误消息，了解具体失败原因
   • 如果遇到速率限制，请考虑减小批次大小

5. 附件问题

   • 未找到文件：确保附件文件路径正确且可访问
   • 权限错误：检查服务器是否拥有附件文件的读取权限
   • 大小限制：Gmail 对每封邮件的附件大小限制为 25MB
   • 下载失败：确认你对下载目录拥有写入权限

参与贡献

欢迎贡献！请随时提交 Pull Request。

分支工作流

此代码库采用双分支模式：

• main - 稳定分支。仅接收在 experimental 中确认可正常运行后提升的更改。PR 绝不会直接合并到 main。
• experimental - 暂存 / 活跃开发分支。所有 PR 都会调整目标分支，并优先合并到 experimental。

贡献的生命周期：

PR opened (any base)
  → retargeted to `experimental`
  → security audit + review + CI
  → merged into `experimental`
  → soak / verify on experimental
  → `experimental` promoted to `main` (maintainer confirms)

请尽可能针对 experimental 创建 PR。如果你将目标设为 main，维护者会在合并前将其调整到 experimental。

CI 要求更新 README - 每次推送到 main 以及每个 PR 都必须包含 README.md 更改（即使只是提升版本号或添加变更日志条目）。这可确保文档随着代码库的发展保持最新。

对于确实不需要更新文档的提交（依赖项升级、CI 配置更改），请在提交消息或 PR 标题中包含 [skip-readme] 或 [no-readme]，以跳过此要求。

运行评测

evals 包会加载一个 MCP 客户端，然后运行 index.ts 文件，因此测试之间无需重新构建。你可以在 npx 命令前加上环境变量来加载这些变量。完整文档见此处。

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts

许可证

MIT

支持

如果你遇到任何问题或有疑问，请提交问题。