内容
# gmail-connector
多账户Gmail MCP服务器。从一个Claude Code、Claude Desktop或Cowork会话中读取多个Gmail收件箱。
## 为什么
Anthropic的官方Gmail连接器绑定到每个工作区的一个账户。如果您有个人+工作+学校Gmail，您不能要求Claude查看所有这些。 这个服务器解决了这个问题。 所有工具都接受`account`参数，`account: "all"`会并行扩展到每个连接的收件箱。
默认情况下为只读。完整的CRUD（发送、草稿、标签、存档、删除）需要`GMAIL_MCP_MODE=full`权限。
## 安装
需要Node 20+。
```bash
npm install -g github:jwlutz/gmail_connector
```
或克隆并链接：
```bash
git clone https://github.com/jwlutz/gmail_connector
cd gmail_connector
npm install && npm link
```
## 设置
您需要一个启用了Gmail API的Google Cloud项目和一个桌面OAuth客户端。有两种方法。
### 方法A：引导式向导（推荐）
```bash
gmail-connector init
```
引导您完成四个Cloud Console页面（项目、Gmail API、身份验证平台、OAuth客户端），在正确的时间打开每个页面。自动检测您下载的`client_secret_*.json`并将其移动到`~/.gmail-connector/oauth-keys.json`。大约需要3分钟。
### 方法B：借用他人的OAuth客户端
如果运行gmail-connector的朋友与您共享他们的`oauth-keys.json`，请将其放入`~/.gmail-connector/oauth-keys.json`并完全跳过Cloud Console。 他们必须将您的Gmail添加到他们项目的测试用户列表中。 有关注意事项，请参见下面的[共享](#共享OAuth凭证)。
### 方法C：手动
如果`init`不适合您，请参见底部的[手动设置](#手动Google Cloud设置)。
## 验证账户
```bash
gmail-connector auth personal # 打开浏览器，登录到您的个人Gmail
gmail-connector auth work # 对每个账户重复此操作，任意别名
gmail-connector accounts # 列出连接的账户
```
`auth <alias>` 打开Google的OAuth流程。 登录到您想要在该别名下的Gmail，点击“未验证的应用”警告（高级 → 继续），授予只读范围即可。
> **7天令牌过期：** 在应用处于测试模式（默认）时，刷新令牌会在7天后过期。 您需要每周重新运行`gmail-connector auth <alias>`。 要使其永久生效，请提交应用以进行Google验证 — 这是针对Gmail范围的多周过程。
## 连接到Claude
### Claude Code
```bash
claude mcp add --scope user gmail-connector $(which gmail-connector)
```
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"gmail-connector": {
"command": "/absolute/path/to/gmail-connector"
}
}
}
```
使用绝对路径。Claude Desktop启动时带有最小的PATH。 使用`which gmail-connector`获取绝对路径。重启Claude Desktop。
### 验证
```bash
claude mcp list # 应该显示：gmail-connector ... ✓ 已连接
```
## 模式
### 只读（默认）
工具：`list_accounts`、`search_emails`、`get_email`、`get_thread`、`list_labels`、`get_attachment`。OAuth范围：`gmail.readonly`。
### 完整CRUD
在服务器运行的环境中设置`GMAIL_MCP_MODE=full`。添加：`send_email`、`create_draft`、`delete_draft`、`modify_labels`、`archive_email`、`trash_email`、`create_label`、`delete_label`。OAuth范围：`gmail.modify` + `gmail.send`。
切换到完整模式后，**为每个账户重新运行`gmail-connector auth <alias>`**，以便Google授予更广泛的范围。 只读令牌不会自动升级。
```json
{
"mcpServers": {
"gmail-connector": {
"command": "/absolute/path/to/gmail-connector",
"env": { "GMAIL_MCP_MODE": "full" }
}
}
}
```
## 工具
所有工具都接受`account: string`作为第一个参数。 读取工具接受`"all"`以扩展到每个连接的账户。
| 工具 | 模式 | 用途 |
|---|---|---|
| `list_accounts` | 两种 | 列出连接的别名。 调用此命令。 |
| `search_emails` | 两种 | Gmail搜索语法，返回元数据 |
| `get_email` | 两种 | 包括正文的完整消息 |
| `get_thread` | 两种 | 线程中的所有消息 |
| `list_labels` | 两种 | 标签（系统 + 用户） |
| `get_attachment` | 两种 | 下载附件字节（base64） |
| `send_email` | 完整 | 明文发送 |
| `create_draft` | 完整 | 创建草稿（未发送） |
| `delete_draft` | 完整 | 删除草稿 |
| `modify_labels` | 完整 | 添加/删除消息上的标签 |
| `archive_email` | 完整 | 删除INBOX标签 |
| `trash_email` | 完整 | 移到回收站（可恢复30天） |
| `create_label`, `delete_label` | 完整 | 管理用户标签 |
## CLI参考
```
gmail-connector 运行MCP服务器（stdio）
gmail-connector init 引导式OAuth设置
gmail-connector auth <alias> 添加或重新验证账户
gmail-connector accounts 列出连接的账户
gmail-connector accounts rename <a> <b> 重命名别名
gmail-connector accounts remove <alias> 删除账户
```
环境变量：
- `GMAIL_MCP_MODE` — `readonly`（默认）或`full`
- `GMAIL_MCP_DIR` — 配置目录覆盖（默认`~/.gmail-connector`）
- `GOOGLE_OAUTH_KEYS_PATH` — 覆盖`oauth-keys.json`的路径
## 令牌存储
令牌静止时使用AES-256-GCM加密。 加密密钥（`~/.gmail-connector/.key`）和账户文件（`~/.gmail-connector/accounts.json`）权限均为`0600`。 `oauth2Client.on("tokens", ...)`处理程序持续旋转刷新令牌，因此账户在Google的令牌轮换后仍然存在，无需重新验证。
除了OAuth流程本身（直接在您和Google之间进行）之外，您的机器上不会留下任何内容。
## 共享OAuth凭证
对于紧密团体（≤ 100人），您可以私下共享`~/.gmail-connector/oauth-keys.json`。 Google设计了用于分发的桌面OAuth客户端，因此这些凭证中的秘密并不是真正的秘密。
收件人将您的JSON放入他们的`~/.gmail-connector/oauth-keys.json`并完全跳过Cloud Console设置。 每个用户直接向Google验证；他们的令牌保留在他们自己的机器上。 **您永远不会看到他们的电子邮件内容** — 您只是OAuth应用程序的开发人员。
注意事项：
- 每个用户必须添加到您的项目的测试用户列表中（测试模式限制为100）
- 所有API调用都会影响您的项目的配额
- 您会看到聚合的API指标，但永远不会看到用户内容
要支持超过100个用户，请提交应用以进行Google验证。
## 手动Google Cloud设置
如果您不想使用`gmail-connector init`:
1. **创建项目**：https://console.cloud.google.com/projectcreate
2. **启用Gmail API**：https://console.cloud.google.com/apis/library/gmail.googleapis.com → 启用
3. **OAuth同意 / 身份验证平台**：https://console.cloud.google.com/auth/overview
- “开始使用” → 用户类型：外部
- 填写应用名称、支持电子邮件、开发人员电子邮件
- 跳过范围屏幕
- 受众选项卡 → 测试用户 → “+ 添加用户” → 您的Gmail（以及您要连接的其他Gmail）
- 保持发布状态：测试中
4. **创建OAuth客户端**：https://console.cloud.google.com/auth/clients
- “创建客户端” → 应用类型：**桌面应用**（不是Web — 桌面应用允许我们需要的回调重定向）
- 名称 → 创建 → 成功模态框中的“下载JSON”
5. **放置JSON**：
```bash
mkdir -p ~/.gmail-connector && chmod 700 ~/.gmail-connector
mv ~/Downloads/client_secret_*.json ~/.gmail-connector/oauth-keys.json
chmod 600 ~/.gmail-connector/oauth-keys.json
```
## 故障排除
**`Access blocked: gmail-connector has not completed the Google verification process`**
将您登录的电子邮件地址添加到项目的测试用户列表中（Google身份验证平台 → 受众 → 测试用户）。
**`Google did not return a refresh_token`**
您之前已经同意，Google没有重新颁发刷新令牌。 访问https://myaccount.google.com/permissions，撤销“gmail-connector”，然后重新运行`gmail-connector auth <alias>`。
**`✓ Connected` from `claude mcp list` but tools not appearing in Claude**
对于Claude Desktop，请确保在`claude_desktop_config.json`中使用绝对路径并重启应用程序。 注意：`claude -p`（打印模式）不会将用户范围的MCP工具显示给模型。 改用交互式`claude`，或依赖于计划任务/ Cowork托管的调度任务，它使用不同的代码路径。
**令牌在7天后过期**
在测试模式下预期如此。 每账户重新运行`gmail-connector auth <alias>`。
MCP 市场