gmail-mcp

一个多账户 Gmail MCP 服务器，面向 AI 智能体（Claude Code 以及其他支持 MCP 的工具），其首要设计目标只有一个：智能体可以自由阅读和起草，但每次发送都必须由人类批准。

之所以构建这个服务器，是因为托管的 Gmail 连接器一次只能绑定一个账户，而且发送时毫无阻碍。本服务器通过短别名（work、school、...）将任意数量的 Gmail 账户绑定在一起，并按风险划分能力：

服务器特意注册为 gmail-accounts（而不是 gmail）：如果你同时还运行托管的 Gmail 连接器，近乎相同的工具名称会让智能体读错邮箱，并给出自信的假阴性结论。

发送闸门的工作原理

1. 智能体暂存一封草稿并请求你批准。

2. 你在自己的终端中运行 gmail-approve，查看确切的 RFC822 载荷，并获得一个与该草稿内容哈希绑定的一次性令牌。

3. 智能体使用令牌调用发送工具。错误的草稿、被编辑过的草稿、重复使用的令牌、过期的令牌：全部拒绝。

发送工具还带有 anthropic/requiresUserInteraction，因此即使在 bypassPermissions 模式下，Claude Code 也会提示人类。令牌 CLI 是一种防错联锁；智能体框架的提示才是强制执行边界。

Related MCP server: Gmail Multi-Inbox MCP Server

设置

需要 Python 3.12+ 和 uv。

1. Google Cloud OAuth 客户端

在 console.cloud.google.com 创建一个项目，启用 Gmail API，创建类型为 Desktop app 的 OAuth 客户端 ID，并将 JSON 下载到：

~/.config/gmail-mcp/client_secret.json

2. 声明你的账户

~/.config/gmail-mcp/accounts.json:

{
  "accounts": [
    { "alias": "personal", "email": "alice.personal@gmail.com" },
    { "alias": "work",     "email": "alice.work@gmail.com" }
  ]
}

3. 授权每个账户

uv sync
scripts/auth-all.sh          # runs the OAuth flow once per alias, skips done ones

每次授权都会根据其别名进行校验：在浏览器中授权错误的 Google 账户会被检测并拒绝，不会静默存储。

4. 在 Claude Code 中注册

claude mcp add gmail-accounts -- uv run --directory /path/to/gmail-mcp --frozen --no-sync gmail-mcp

日常使用

每个工具都接受一个 account 别名。你可以让智能体做类似“搜索 work 中的发票会话”或“在 personal 上起草回复”的事情。到需要发送时：

gmail-approve            # lists pending sends, shows the payload, mints a token

健康检查：

uv run gmail-mcp-health

安全说明

• 机密永远不会进入仓库：client_secret.json 和每个账户的令牌存放在 ~/.config/gmail-mcp/ 中（可通过 GMAIL_MCP_CONFIG 覆盖）。

• 所有配置写入都是原子的（tmp + fsync + rename）；写入过程中崩溃绝不会留下残缺文件。

• stdout 是 JSON-RPC 通道；包内任何代码都不得 print()（由 ruff T201 强制执行），因此诊断信息不会破坏协议。

测试

uv run pytest