Gmail Cleanup MCP Server

一个专注于 Gmail 收件箱清理的 Model Context Protocol 服务器 — 将邮件移到回收站、管理过滤器、提取退订链接。旨在补充 Anthropic 内置的 Gmail 连接器，后者负责读取、搜索、草稿和发送。

这是 dcerniglia/gmail-cleanup-mcp 的修补分支（MIT 许可）。该分支修复了一个 bug：search_and_trash 和 batch_trash_emails 过去会静默丢弃失败而不重试 — 同时发出 50 个并发删除请求可能会触发 Gmail 的速率限制，并在不显示任何错误的情况下丢弃约一半批次。现在这两个工具都会以更小的批次处理、退避、自动重试，并针对每条失败消息报告实际错误。

工具

Related MCP server: Gmail AutoAuth MCP Server

前置要求

• Node.js 18+

• 一个启用了 Gmail API 的 Google Cloud 项目

• OAuth 2.0 凭据（桌面应用类型）

设置

1. Google Cloud OAuth

已经有来自其他 Gmail MCP 服务器的 ~/.gmail-mcp/gcp-oauth.keys.json？ 跳到第 2 步 — 此服务器使用相同的凭据位置。

1. 转到 Google Cloud Console

2. 创建项目（或复用现有项目）并启用 Gmail API

3. 转到 凭据 → 创建凭据 → OAuth 客户端 ID

4. 选择 桌面应用，下载 JSON

5. 将其保存为 ~/.gmail-mcp/gcp-oauth.keys.json（或将 gcp-oauth.keys.json 放在项目目录中 — 首次运行时会自动复制）

2. 安装与构建

git clone https://github.com/davidcerniglia/gmail-cleanup-mcp.git
cd gmail-cleanup-mcp
npm install
npm run build

3. 身份验证

npm run auth

这会在浏览器中打开 Google OAuth 授权页面。凭据将保存到 ~/.gmail-mcp/credentials.json，权限为 0600（仅所有者）。

4. 添加到 Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

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

对于 Claude Code，则添加到 .claude/settings.json：

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

使用示例

与 Claude 内置 Gmail 的配合方式

安全性

• 最小权限范围：gmail.modify + gmail.settings.basic — 执行回收站和过滤器操作所需的最小权限

• 移到回收站，而非永久删除：所有删除操作都使用 Gmail 的回收站（30 天恢复期），绝不会永久删除

• 试运行模式：search_and_trash 可以在执行前预览匹配结果

• 严格的文件权限：凭据以 0600 权限存储（仅所有者可读写）

• 不处理附件：零路径遍历风险

• 不访问任何文件系统，仅 ~/.gmail-mcp/ 中的凭据存储除外

环境变量

许可证

MIT