gmail-multi-mcp-server

一个将 Claude 连接到多个 Gmail 账户的 MCP 服务器，暴露与内置 Gmail 连接器相同的工具接口。每个工具都接受一个额外的 account 参数，用于指定要操作的邮箱——这是与单邮箱连接器唯一的结构性差异。

"Check my work inbox for anything from the lender, and draft the reply from my personal account."

为什么存在

内置的 Gmail 连接器只授权一个邮箱。如果你使用多个独立账户——工作、个人、公司别名——就必须不断切换。此服务器保存你授权的所有 Gmail 账户的凭据，并将每次调用路由到你指定的那个账户。

Related MCP server: multiGmailMCP

要求

• Node.js 20 或更高版本

• 一个启用了 Gmail API 的 Google Cloud 项目，以及一个类型为 桌面应用 的 OAuth 客户端

1. 获取 Google OAuth 客户端

1. 打开 Google Cloud Console 并选择或创建一个项目。

2. 在 API 和服务 → 库 中启用 Gmail API。

3. 前往 API 和服务 → OAuth 同意屏幕 进行配置。当应用处于 测试 状态时，在 测试用户 下添加你计划连接的每个 Gmail 地址。

4. 前往 API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID，应用类型选择 桌面应用。下载 JSON 文件。

桌面应用客户端允许在任何端口上进行环回重定向，add-account 流程使用的正是这一点。

2. 安装并构建

git clone <this repo>
cd Gmail-MCP
npm install
npm run build

3. 让服务器使用你的 OAuth 客户端

选择其中一种方式：

# Option A — save the downloaded JSON where the server looks by default
mkdir -p ~/.gmail-mcp && cp ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

# Option B — point at it explicitly
export GMAIL_MCP_CREDENTIALS=/path/to/client_secret.json

# Option C — pass the values directly
export GMAIL_MCP_CLIENT_ID=...apps.googleusercontent.com
export GMAIL_MCP_CLIENT_SECRET=...

4. 授权每个邮箱

每个 Gmail 账户运行一次：

node dist/index.js add-account --alias work
node dist/index.js add-account --alias personal
node dist/index.js list-accounts

每次运行都会打印一个 Google 同意 URL，在本地环回端口上等待重定向，并存储生成的刷新令牌。在无头机器上，添加 --manual 参数并粘贴重定向后的 URL。

服务器运行期间添加的账户会被自动识别——无需重启。

5. 连接到 Claude

Claude Code

claude mcp add gmail-multi -- node /absolute/path/to/Gmail-MCP/dist/index.js

Claude Desktop — 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": ["/absolute/path/to/Gmail-MCP/dist/index.js"],
      "env": {
        "GMAIL_MCP_CREDENTIALS": "/absolute/path/to/client_secret.json"
      }
    }
  }
}

选择账户

除 list_accounts 之外，每个工具都接受 account。匹配顺序为：

1. 完整的电子邮件地址 — mikael@example.com

2. 在 add-account 时设置的别名 — work

3. @ 前面的本地部分 — mikael

4. 任何无歧义的前缀

当只配置了一个邮箱时，或设置了 GMAIL_MCP_DEFAULT_ACCOUNT 时，account 是可选的。否则它是必填的，错误信息会列出可用的账户。

ID 是按邮箱隔离的。 来自一个账户的消息、会话、草稿或标签 ID 在另一个账户中没有意义。出现 “not found” 错误通常意味着传入了错误的 account。

工具

共 35 个工具——即连接器的完整工具集，外加两个用于多账户的工具。

工具名称特意与 Gmail 连接器保持一致，因此提示词和使用习惯都可以沿用。MCP 客户端按服务器对工具进行命名空间隔离，因此两者可以同时启用而不会冲突。

与内置连接器的差异

以下内容都是新增功能——连接器的行为在这里不会有任何变化。

• 每个工具上都有 account，外加 list_accounts 和 get_profile。

• 每个工具都支持 response_format（markdown | json）。默认值为 markdown，保持简洁；无论如何，完整的结构化负载都会作为 structuredContent 返回。

• delete_draft 和 get_message_attachment，连接器有引用但未暴露。

• reply 接受 quoteOriginal（默认 false），用于将原邮件作为引用块附加。

• forward 接受 includeAttachments（默认 true）；将其设为 false 可跳过大型附件。

• get_message_attachment 接受 savePath，用于将文件写入磁盘，而不是内联 base64。

• 响应限制为 25,000 个字符，会先压缩分页列表，并明确说明丢弃了什么以及如何获取其余部分。

值得了解的行为

• search_threads 返回每个会话最早邮件的预览（约 5 封），与连接器类似。在回答任何关于最近或未读邮件的问题之前，请先调用 get_thread。

• 除非查询中提到草稿，否则 search_threads 会排除草稿。请使用 list_drafts。

• 标签通过 ID 来引用，而不是显示名称。请先调用 list_labels。

• DRAFT 和 SENT 是只读的；添加 TRASH/SPAM 会路由到 apply_sensitive_* 工具，因此破坏性操作总是被明确命名。

• update_draft 会合并字段，但附件是替换而不是合并——响应会报告丢弃了多少个附件。

• reply 会设置 In-Reply-To 和 References，以便客户端能正确地将邮件归入会话，并且绝不会将回复地址指向已授权的邮箱本身。

安全性

• 刷新令牌保存在 ~/.gmail-mcp/accounts.json 中，在 0700 目录内以 0600 权限原子写入。任何能读取该文件的人都拥有对邮箱的完全访问权限。

• OAuth 流程会校验 state 参数，并且只监听 127.0.0.1。

• remove-account 会删除本地令牌。要完全撤销，还需在 myaccount.google.com/permissions 中移除该应用。

• 授予的权限范围允许读取、发送和删除邮件。send_message、reply 和 forward 会立即发送——工具描述会指示模型在用户未明确要求发送邮件时优先使用 create_draft。

开发

npm run build         # compile TypeScript to dist/
npm test              # build, then unit tests + stdio smoke test
npm run test:unit     # MIME, reply addressing, parsing, truncation — no network
npm run test:smoke    # boots the server, checks all 35 tools register
npm run inspect       # open the MCP Inspector against the server

src/
  index.ts            CLI entry point and server bootstrap
  constants.ts        scopes, limits, paths
  types.ts            normalized message/thread/draft shapes
  auth/               token store, OAuth flow, account registry
  schemas/common.ts   shared Zod fields (account, formats, pagination, colors)
  services/           Gmail parsing, MIME building, formatting, errors
  tools/              tool registration by domain

故障排除

许可证

MIT