multi-gmail-mcp

multi-gmail-mcp

一个 Model Context Protocol（MCP）服务，可让 Claude Desktop 同时管理多个 Gmail 账号。已列入 Anthropic 官方 MCP 注册表，并发布在 npm 上。

---

功能

• 连接不限数量的 Gmail 账号——个人、工作和副业项目账号
• 使用完整的 Gmail 搜索语法搜索任意收件箱
• 解析 MIME 格式，读取完整邮件
• 发送邮件、在会话中回复和创建草稿
• 使用标签进行整理：添加、移除、列出、归档
• 标记为已读 / 未读
• 令牌存储在本地的 ~/.gmail-mcp-tokens.db 中——绝不会提交到 git
• 自动静默刷新 OAuth 令牌

---

要求

• Node.js >= 22.5.0
• 已启用 Gmail API 的 Google Cloud 项目
• Claude Desktop

---

安装

npm install -g multi-gmail-mcp

这会注册两个全局命令：gmail-mcp（MCP 服务）和 gmail-mcp-cli（账号管理器）。

---

Google Cloud 设置

只需设置一次。

1. 前往 console.cloud.google.com → 创建项目
2. 启用 Gmail API（APIs & Services → Library）
3. 配置 OAuth 同意屏幕——选择 External，并将你的 Gmail 地址添加为测试用户
4. 添加作用域：gmail.readonly、gmail.send、gmail.modify、gmail.labels
5. 创建 Desktop app OAuth 凭据 → 下载 JSON 文件
6. 将其保存到 ~/.gmail-mcp-oauth.json

或者，在 Claude Desktop 配置中设置环境变量（见下文）。

---

验证 Gmail 账号

# Add accounts (opens browser for Google sign-in)
gmail-mcp-cli add [email protected]
gmail-mcp-cli add [email protected]

# List authenticated accounts
gmail-mcp-cli list

# Remove an account
gmail-mcp-cli remove [email protected]

令牌会保存到 ~/.gmail-mcp-tokens.db，并自动刷新。

---

Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "multi-gmail": {
      "command": "gmail-mcp"
    }
  }
}

如果你更希望使用环境变量，而非 ~/.gmail-mcp-oauth.json：

{
  "mcpServers": {
    "multi-gmail": {
      "command": "gmail-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

保存后重启 Claude Desktop。点击锤子图标，确认已加载 19 个工具。

---

可用工具

账号管理

工具	描述
list_accounts	列出所有已通过身份验证的 Gmail 账号
initiate_auth	启动 OAuth 流程——返回一个可在浏览器中打开的 URL
complete_auth	完成 Google 登录后结束身份验证
remove_account	移除账号及其已存储的凭据

阅读邮件

工具	描述
search_emails	使用 Gmail 语法搜索（is:unread、from:、after: 等）
get_email	根据邮件 ID 获取完整邮件内容

撰写邮件

工具	描述
send_email	发送邮件（支持 To、CC、BCC）
reply_to_email	在会话中回复，并保留 References 标头
create_draft	将邮件保存为草稿

整理

工具	描述
list_labels	列出账号的所有 Gmail 标签
add_label	为邮件添加一个或多个标签
remove_label	从邮件中移除一个或多个标签
archive_email	从收件箱中移除
mark_as_read	移除 UNREAD 标签
mark_as_unread	添加 UNREAD 标签

---

示例提示词

List all my authenticated Gmail accounts.

Search my [email protected] inbox for unread emails from this week.

Reply to that email from my personal account saying I'll be there Saturday.

Send an email from [email protected] to [email protected]
with subject "Dinner plans" and body "Are you free Saturday?"

Archive everything older than a week in my side-project inbox that's already read.

Check both my accounts for emails from GitHub and summarize them.

---

安全性

• ~/.gmail-mcp-oauth.json 和 ~/.gmail-mcp-tokens.db 位于你的主目录中——不在项目目录内，绝不会提交
• .gitignore 会排除 *.db、.gmail-mcp-oauth.json 和 .env
• 服务仅通过 stdio 运行——不会开放网络端口
• OAuth 作用域仅限于必需的最小范围

完整详情请参阅 SECURITY.md，包括令牌存储、网络行为、作用域说明、撤销步骤以及如何报告漏洞。

---

注册表

已列入 Anthropic 官方 MCP 注册表：

io.github.gx-55/multi-gmail-mcp

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.gx-55"

---

项目结构

multi-gmail-mcp/
├── bin/
│   ├── gmail-mcp.js        # Entry point for the MCP server command
│   └── gmail-mcp-cli.js    # Entry point for the CLI command
├── src/
│   ├── server.js           # MCP server — all 19 tools
│   ├── gmail-client.js     # Gmail API wrapper
│   ├── auth.js             # OAuth2 flow with auto-refresh
│   ├── db.js               # SQLite token storage (node:sqlite)
│   └── cli.js              # Account management CLI
└── package.json

---

故障排除

“未找到 OAuth 凭据” 确保 ~/.gmail-mcp-oauth.json 存在，或在 Claude Desktop 配置中设置 GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET。

“未找到账号。请先进行身份验证” 在 Claude 中使用该账号之前，先运行 gmail-mcp-cli add [email protected]。

Claude Desktop 中未显示工具 确认 gmail-mcp 位于 PATH 中（which gmail-mcp），然后重启 Claude Desktop。

令牌过期错误 如果已存储有效的刷新令牌，令牌会自动刷新。如果刷新失败，请移除该账号并重新进行身份验证：gmail-mcp-cli remove [email protected] && gmail-mcp-cli add [email protected]。