内容
# gmail-multi-mcp
将**多个 Gmail 账户**连接到 Claude（或任何 [MCP](https://modelcontextprotocol.io) 客户端），只需一个本地服务器。官方的 Gmail 连接器仅支持单个 Google 账户 — 本项目允许您跨多个账户搜索、阅读、草拟、发送、标记和组织邮件，每个账户都可以通过友好的别名来访问。
您的 OAuth 令牌仅存储在**本地计算机上** — 永远不会上传到任何地方。
## 功能
- 🔢 **无限账户** — 每个工具都接受一个 `account` 参数（`"personal"`、`"work"` 等）
- 🔎 **搜索和阅读** — 完整的 Gmail 搜索语法、线程/消息阅读、附件下载
- ✍️ **草拟** — 创建/列出/删除草稿、发送邮件、带有正确线程标头的回复
- 🏷️ **组织** — 完整的标签管理、存档、删除
- 🔐 **本地优先** — 标准 Google OAuth；令牌存储在 `~/.gmail-mcp/` 中，chmod 600
- 🧩 **22 种工具**，与 Claude Code、Claude Desktop、Cursor 以及任何 MCP 客户端兼容
## 先决条件
- **Node.js ≥ 20**
- 一个 Google 账户（以及一个免费的 Google Cloud 项目 — 参见下面的设置）
## 1. 安装
```bash
git clone https://github.com/Vinksj/claude-gmail-multi.git
cd claude-gmail-multi
npm install
npm run build
```
## 2. 创建 Google OAuth 应用（一次性，大约 10 分钟）
您只需向 Google 注册一个 OAuth 应用；然后它将适用于您连接的所有账户。
1. 进入 [console.cloud.google.com](https://console.cloud.google.com) → 创建一个项目（例如 `gmail-mcp`）。
2. **APIs & Services → Library** → 搜索 **Gmail API** → **启用**。
3. **APIs & Services → OAuth 同意屏幕**：
- 用户类型 **外部** → 创建。
- 应用名称 + 您的支持电子邮件 + 联系电子邮件 → 保存并继续。
- 作用域页面 → 保存并继续。测试用户页面 → 保存并继续。
4. **发布到生产环境：** 在 OAuth 同意屏幕上，设置 **发布状态 → 发布应用**。
*(在“测试”模式下，Google 每 7 天都会使您的刷新令牌过期。发布可以避免这种情况。
您将点击一次“Google 尚未验证此应用”的警告 — 这对于个人应用来说是正常的：选择 **高级 → 继续**.)*
5. **APIs & Services → 凭证 → 创建凭证 → OAuth 客户端 ID**：
- 应用类型 **桌面应用** → 创建 → **下载 JSON**。
6. 将该文件保存为 `~/.gmail-mcp/credentials.json`：
```bash
mkdir -p ~/.gmail-mcp && chmod 700 ~/.gmail-mcp
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json
```
> 注意：较新的 Google Cloud 界面将这些放在 **“Google Auth Platform”** （品牌/受众/客户端）下，而不是“OAuth 同意屏幕” — 相同的步骤，不同的标签。
## 3. 连接您的账户
```bash
npm run auth -- --alias personal --email you@gmail.com
npm run auth -- --alias work --email you@company.com
```
每个命令都会打开一个浏览器 → 选择匹配的 Google 账户 → 批准。可选的 `--email` 参数会在错误账户被授权时中止（使用多登录浏览器时容易出错）。连接任意多个账户；如果令牌被撤销，请随时重新运行。
## 4. 在您的 MCP 客户端中注册
**Claude Code:**
```bash
claude mcp add --scope user gmail-multi -- node "$(pwd)/dist/index.js"
```
**Claude Desktop / 其他客户端** — 添加到您的 MCP 配置：
```json
{
"mcpServers": {
"gmail-multi": {
"command": "node",
"args": ["/absolute/path/to/gmail-multi-mcp/dist/index.js"]
}
}
}
```
工具显示为 `gmail-multi` 的 `search_threads`、`create_draft` 等。您可以询问诸如 *"搜索我的工作邮箱中本周的未读邮件"* 或 *"在个人账户中草拟一封给 Alice 的回复"*。
## 工具
| 分组 | 工具 |
|---|---|
| 账户 | `list_accounts`、`add_account` |
| 阅读 | `search_threads`、`get_thread`、`get_message`、`download_attachment` |
| 草拟 | `create_draft`、`list_drafts`、`delete_draft`、`send_draft`、`send_message` |
| 标签 | `list_labels`、`create_label`、`update_label`、`delete_label`、`label_thread`、`unlabel_thread`、`label_message`、`unlabel_message` |
| 清理 | `archive_thread`、`trash_thread`、`trash_message` |
除 `list_accounts` 外，每个工具都接受一个 `account` 参数（别名或电子邮件）。通过 `replyToMessageId` 发送的回复具有正确的 `In-Reply-To`/`References` 标头和自动线程。
## 工作原理
- 一个自有 Google Cloud OAuth 应用（桌面客户端）授权任意数量的账户。
- 单个作用域：`https://www.googleapis.com/auth/gmail.modify`（读取、搜索、草稿、发送、标签、存档、删除 — 比完整的 `https://mail.google.com/` 更窄）。
- 每个账户的刷新令牌存储在 `~/.gmail-mcp/tokens/<alias>.json` 中（chmod 600）；账户注册表存储在 `~/.gmail-mcp/config.json` 中。没有任何信息离开您的机器。
```
~/.gmail-mcp/
├── credentials.json # 您的 OAuth 客户端（您添加此文件）
├── config.json # 别名 → 电子邮件映射（自动管理）
└── tokens/<alias>.json # 每个账户的刷新令牌（自动管理）
```
## 安全说明
- 令牌存储为普通文件，仅由您的用户可读（chmod 600）。在具有全盘加密的单用户机器上，这是合理的；将令牌存储移动到 OS 密钥链是一个明智的未来强化步骤。
- 永远不要提交 `~/.gmail-mcp/` — 它位于您的主目录中，位于此仓库之外，并且仓库的 `.gitignore` 排除构建工件和依赖项，无论如何。
- `gmail.modify` 作用域无法永久删除邮件 — `trash_*` 工具将项目移动到垃圾箱（可恢复 30 天）。
## 开发
```bash
npm run build # tsc -> dist/
npm run inspect # MCP Inspector UI 对抗内置服务器
npm run auth -- --alias <name> [--email <expected>]
```
重要：stdout 是 JSON-RPC 通道 — 永远不要在服务器代码中 `console.log`；请使用 `console.error`。
## 许可证
MIT © Saurabh Jain
