gmail-tidy-mcp

gmail-tidy-mcp

一个 MCP 服务，让你的 AI 助手可以同时读取和整理多个 Gmail 帐户：搜索、阅读、添加标签、归档、设置过滤器和撰写草稿。

它不能发送或删除邮件。不是“它会先征求确认”：它根本没有相应工具，而且如果代码中出现任何发送或删除调用，测试就会导致构建失败。

为什么开发它

大多数 Gmail MCP 服务会把邮箱的完全控制权交给模型，包括发送邮件，还会将 OAuth 令牌以纯文本形式保存在磁盘上。把这么多信任交给一个也会读取陌生人所写邮件的模型，风险很高。

这个服务的承诺更为有限：助手可以帮你整理收件箱，但不能发送或删除任何内容。

它能做什么

区域	工具
帐户	list_accounts、check_accounts、connect_account、finish_connect_account
阅读	search_emails（Gmail 搜索语法）、search_all_accounts（一次搜索所有帐户）、get_email（列出附件）、get_thread（完整会话，按时间从早到晚排列，并精简引用历史）、get_attachment（文本、.gz 和 .zip 文件会直接读取，例如 DMARC 报告；其他文件，如 PDF，则保存到 ~/Downloads/gmail-tidy-mcp）、sender_stats（按地址和域名统计最常写信的人）、newsletters（按邮件数量列出邮件列表及其声明的退订链接；它不会代你退订）
标签	list_labels、create_label（使用 Parent/Child 创建嵌套标签）、update_label（重命名、使用 Gmail 调色板更改颜色、在侧边栏中显示或隐藏）
整理	organize_emails：按 ID 或搜索结果添加或移除标签，每次最多处理 5,000 封邮件。归档 = 移除 INBOX，标记为已读 = 移除 UNREAD
过滤器	list_filters、create_filter、delete_filter。跳过收件箱的过滤器必须明确设置 skip_inbox: true
草稿	create_draft，可选择在会话中撰写回复并附加本地文件；list_drafts；update_draft 编辑现有草稿（只更改你传入的字段，会话和现有附件保持不变）。你可以自行在 Gmail 中发送
设置	set_signature：只更改签名，不会更改邮件的发送方式
审计	recent_changes：记录此服务进行的每项更改，供你检查或撤销本次会话中的操作

每个帐户都会分配一个简短标签，因此你可以说“归档 work 中所有一个月前的新闻邮件”。

它不会做什么

• 发送、回复、转发或删除邮件，也不会将邮件移至“已删除邮件”或“垃圾邮件”。
• 不会给模型提供以后添加这些功能的途径：工具在代码中固定，模型无法调用任意 Gmail 端点。

Google 没有允许创建草稿但禁止发送邮件的权限范围，因此此服务会申请 gmail.modify（该权限在技术上也包含发送邮件）以及用于过滤器的 gmail.settings.basic。安全保证来自代码，test/safety.test.js 会在每次运行时检查这一点。

安全性

• 令牌已使用 AES-256-GCM 加密，存储在 ~/.config/gmail-tidy-mcp/tokens.enc（权限模式为 600）中。密钥存放在 macOS 钥匙串、Linux Secret Service（secret-tool）或 Windows 上受 DPAPI 保护的文件中。你也可以通过 GMAIL_TIDY_KEY（64 个十六进制字符）自行提供密钥。
• 登录使用 PKCE 和随机的 state，且仅重定向到 127.0.0.1。
• 已验证登录账号。 登录后，服务会向 Gmail 查询实际登录的地址。如果地址与你指定的不符，或者 Google 授予了不同的权限范围，令牌就会被撤销，且不会保存任何内容。
• 使用你自己的 OAuth 客户端。 不使用共享客户端或第三方服务。你的邮件只会从 Google 发送到你的设备，不会去往其他地方。
• 邮件内容会被隔离为不可信内容。 从 Gmail 读取的所有内容都会放入一个区块中，其标记每次调用都会使用随机值，因此邮件无法提前闭合区块。系统会移除标头中的控制字符，并将 HTML 转换为可见文本（会删除脚本、样式，以及通过 display:none、visibility:hidden、font-size:0 或 opacity:0 隐藏的文本）。
• 会移除不可见文本。 系统会从标头、正文和附件中剥离 Unicode 标签字符（可用于夹带模型能读取而你看不到的指令）、零宽字符和文本方向控制符。系统会报告标签字符，因为它们在邮件中没有正当用途。
• 安全提示由服务生成，而非发件人提供。 get_email 和 get_attachment 会在不可信内容区块上方添加简短的发现列表：典型的提示词注入措辞、SPF、DKIM 或 DMARC 验证失败、发件人未通过 DMARC 时将回复发送到免费 Webmail 地址的 Reply-To、伪装成其他地址的显示名称，以及显示一个网站却指向另一个网站的链接（会先展开 Gmail 和 Outlook 的重定向链接；不会标记邮件列表中的跟踪链接）。这些检测经过调整，不会对普通邮件频繁发出提示，因此出现提示就说明确实有问题。
• 会标记相似的发件人。 如果发件人的域名与你已连接账号的域名相差一两个字母，或使用了外形类似拉丁字母的其他文字系统中的字母，就会收到提示；对于 Gmail 和其他 Webmail 服务，则改为比较邮箱名称。你自己的账号之间互发的邮件绝不会被标记。
• 草稿只能附加来自用户文件夹的文件。 附件必须位于 Downloads、Desktop 或 Documents 中（或位于 GMAIL_TIDY_ATTACH_DIRS 指定的文件夹中），不能位于隐藏文件夹，也不能来自本服务自己的配置目录。检查前会解析链接，因此快捷方式不能指向 ~/.ssh。这样，受恶意邮件操纵的模型就无法将私钥或令牌塞进草稿让你发送。
• 每项更改都会在本地记录。 标签、归档操作、过滤器、草稿、签名更改和保存的文件都会追加记录到 ~/.config/gmail-tidy-mcp/audit.log（权限模式为 600），且不会记录邮件正文、草稿文本或签名内容。recent_changes 会显示这些记录，因此如果某个会话中发生了异常情况，你可以准确查看发生了什么并撤销操作。
• 不会保存危险附件。 可执行文件和脚本、伪装名称的文件（factura.pdf.exe、从右向左覆盖字符等技巧）、字节内容与扩展名不符的文件，以及包含上述任一文件的压缩包，都会被拒绝，除非调用参数指定 allow_risky: true。受密码保护的压缩包、启用宏的 Office 文件，以及包含 JavaScript 或自动运行操作的 PDF 会被标记。保存的文件绝不会覆盖任何内容，也无法写入下载文件夹之外；在 macOS 上还会添加隔离标记，以便 Gatekeeper 在文件打开前进行检查。
• 草稿无法夹带标头。 To、Cc、Subject 或回复标头中的换行符都会被拒绝，因此任何人都无法偷偷加入隐藏的 Bcc。
• 参数在传给 Gmail 前都会经过验证，会更改内容的工具还带有 MCP 注释（destructiveHint），客户端可在运行前征求你的确认。
• 大型扫描会遵守 Gmail 配额。 sender_stats、newsletters 和搜索功能每次只获取少量邮件，并会在 Gmail 要求时退避，因此大型邮箱只会让扫描变慢，而不会导致失败。
• 两个运行时依赖（@modelcontextprotocol/sdk 和 googleapis）均固定为确切版本，且都没有安装脚本。

仍可能出现的问题

没有任何服务能让提示词注入成为不可能，安全说明也只是启发式规则：它们能识别常见手法，但无法识别所有手法；检查结果干净并不能证明没有问题。如果恶意邮件说服了模型，它仍可能：

• 重新标记或归档邮件（你可以撤销），
• 创建隐藏收件箱中新邮件的过滤器（仅当设置了 skip_inbox: true 时才会这样，而且客户端可以先询问你），
• 删除你的某个过滤器（过滤器无法恢复），
• 写一封误导性的草稿。除非你亲自发送，否则它永远不会发出，
• 重命名或更改标签颜色、更改签名，或改写你的某个草稿（这些操作都可撤销：审计日志会记录更改内容），
• 保存被标记为危险的附件（前提是同时设置了 allow_risky: true）；是否打开仍由你决定。

还有两点值得了解：

• 令牌本身可以发送邮件。“绝不发送”的保证来自这段代码，而不是令牌。如果有人同时盗走令牌和密钥，他们就能执行 gmail.modify 允许的操作。请锁好你的设备和密钥环。
• 在 macOS 上，钥匙串项目信任 /usr/bin/security，这意味着任何以你的身份运行的进程都能在无需提示的情况下读取密钥。这样仍能避免密钥存储在磁盘上，但无法抵御以你的用户身份运行的恶意软件。

设置

需要 Node.js 22 或更高版本。

1. 创建 Google OAuth 客户端（只需一次）

1. 在 Google Cloud Console 中创建项目并启用 Gmail API。
2. 在 Google Auth Platform 中，将应用设置为 External，将你的电子邮件地址添加为支持和联系地址，然后发布应用（Audience → Publish app）。未验证的应用在生产模式下会保留刷新令牌。在测试模式下，刷新令牌会在 7 天后过期。
3. 在 Clients 下创建一个 Desktop app 类型的客户端，并下载 JSON 文件。
4. 将其保存为 ~/.config/gmail-tidy-mcp/oauth-client.json，并限制文件访问权限（在 macOS 和 Linux 上运行 chmod 600）。

连接账号时，Google 会警告你该应用未经验证。这是正常的：该应用属于你。请通过 Advanced 继续。

2. 在 MCP 客户端中注册

Claude Code：

claude mcp add -s user gmail-tidy -- npx -y gmail-tidy-mcp

其他 MCP 客户端：通过标准输入/输出运行 npx -y gmail-tidy-mcp。

想从源代码运行？克隆仓库，运行 npm ci --ignore-scripts，然后将客户端指向 node /path/to/gmail-tidy-mcp/bin/gmail-tidy-mcp.js。

在 Linux 上，请先安装 libsecret-tools，以便将密钥存入密钥环。

3. 连接账号

请助手连接一个账号。它会在浏览器中打开 Google 登录页面。也可以在终端中操作：

npx gmail-tidy-mcp add [email protected] personal
npx gmail-tidy-mcp list
npx gmail-tidy-mcp remove [email protected]

移除账号会在本地删除其令牌。若要同时在 Google 端撤销访问权限，请前往 myaccount.google.com/permissions。

Google Workspace 账号可能需要管理员允许使用未经验证的应用。

开发

npm test

测试涵盖安全保证（不调用发送或删除操作、不使用 Trash 或 Spam、过滤器操作仅限标签）、令牌加密和密钥处理、登录回调（状态、错误、超时）、登录后的检查、草稿标头和正文解码。CI 会在 Linux、macOS 和 Windows 上运行这些测试，包括 Windows 上实际的 DPAPI 路径。

致谢

本项目基于 Rogers Xie 编写的 gx-55/multi-gmail-mcp（MIT）起步。项目保留了其中的一些构建模块：按标签或地址查找账号、邮件搜索和标头辅助函数、回复邮件串联以及令牌错误检测。存储、登录流程、工具集和安全模型均已重新设计。

许可证

MIT。请参阅 LICENSE。