Gmail多收件箱MCP服务器
> 一个模型上下文协议(MCP)服务器,使AI助手能够通过内置的OAuth身份验证同时管理多个Gmail帐户。
为什么选择MCP服务器?
与现有的Gmail MCP服务器不同,此实现提供了:
- 多账户支持:从单个MCP服务器实例管理多个Gmail帐户
- 智能聚合:同时读取和搜索所有帐户
- 内置OAuth流:通过MCP工具完成身份验证设置-无需手动生成令牌
- 类型安全:使用TypeScript构建,具有可靠性和更好的IDE支持
- 自动令牌刷新:自动处理令牌过期并保存刷新的令牌
- 综合API:完整的Gmail API覆盖范围,包括标签、帖子、草稿等
目录
- 特性
- 先决条件
- 安装
- 谷歌云设置
- 配置
- 铁路/SSE部署
- OAuth入职培训
- 使用示例
- API 参考
- 故障排除
- 贡献
- 许可证
特性
读取操作
list_accounts-查看所有已配置的帐户及其状态read_emails-获取最近的电子邮件(默认情况下聚合所有帐户)search_emails-使用Gmail查询语法跨多个帐户搜索get_email_thread-检索完整的对话线索get_labels-列出帐户的所有标签
写入操作
send_email-从任何配置的帐户发送电子邮件,并可选择本地文件附件create_draft-创建带有可选本地文件附件的草稿消息delete_drafts-按草稿ID永久删除一个或多个草稿mark_as_read-将邮件标记为已读archive_emails-存档邮件(从收件箱中删除)trash_emails-将邮件移至垃圾箱
标签管理
add_labels-为邮件应用标签remove_labels-从邮件中删除标签create_label-创建新的自定义标签delete_label-删除现有标签
账户管理
begin_account_auth-为新帐户启动OAuth流finish_account_auth-完成OAuth并保存凭据
先决条件
- Node.js 20+ (下载)
- 谷歌云项目 启用Gmail API
- OAuth 2.0凭据 (桌面应用程序类型)
安装```bash
Clone the repository
git clone https://github.com/tszaks/gmail-multi-inbox-mcp.git
cd gmail-multi-inbox-mcp
Install dependencies
npm install
Build the TypeScript code
npm run build
## 谷歌云设置
在使用此MCP服务器之前,您需要设置一个Google Cloud项目:
### 1.创建谷歌云项目
1. 首选 谷歌云控制台
1. 创建新项目或选择现有项目
1. 记下您的项目ID
### 2.启用Gmail API
1. 在您的项目中,请访问 **API和服务** > **图书馆**
1. 搜索“Gmail API”
1. 点击 **启用**
### 3.创建OAuth 2.0凭据
1. 首选 **API和服务** > **凭证**
1. 点击 **+创建凭据** > **OAuth客户端ID**
1. 如果出现提示,请配置OAuth同意屏幕:
- 选择“外部”用户类型
- 填写必填字段(应用程序名称、支持电子邮件)
- 将您的电子邮件添加到测试用户
1. 对于应用程序类型,选择 **桌面应用**
1. 为其命名(例如,“Gmail MCP客户端”)
1. 点击 **创建**
1. **下载JSON文件** -你需要这个进行身份验证
### 4.OAuth同意屏幕设置
1. 首选 **API和服务** > **OAuth 同意屏幕**
1. 添加以下范围:
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/gmail.send`
- `https://www.googleapis.com/auth/userinfo.email`
1. 将您的Gmail地址添加为测试用户
## 配置
### 添加到您的MCP设置
将此服务器添加到您的 `.mcp.json` 配置文件(调整路径以匹配您的安装):```json
{
"mcpServers": {
"gmail-multi": {
"command": "node",
"args": [
"/path/to/gmail-multi-inbox-mcp/dist/index.js"
]
}
}
}
自定义配置目录(可选)
要使用自定义目录存储帐户数据,请执行以下操作:```json
{
"mcpServers": {
"gmail-multi": {
"command": "node",
"args": [
"/path/to/gmail-multi-inbox-mcp/dist/index.js"
],
"env": {
"GMAILMCPCONFIG_DIR": "/custom/path/.gmail-multi-mcp"
}
}
}
}
服务器也接受旧版 `GMAIL_MCP_CONFIG_DIR` 有人是。
### 目录结构
默认配置位置: `~/.gmail-multi-mcp/````
~/.gmail-multi-mcp/
├── accounts.json # Master account list
└── accounts/
├── personal/
│ ├── credentials.json # OAuth client credentials
│ ├── token.json # Access/refresh tokens
│ └── meta.json # Account metadata
└── work/
├── credentials.json
├── token.json
└── meta.json
accounts.json格式```json
{
"defaultAccount": "personal",
"accounts": [
{
"id": "personal",
"email": "user@gmail.com",
"displayName": "Personal Gmail",
"enabled": true,
"credentialPath": "~/.gmail-multi-mcp/accounts/personal/credentials.json",
"tokenPath": "~/.gmail-multi-mcp/accounts/personal/token.json"
},
{
"id": "work",
"email": "user@company.com",
"displayName": "Work Email",
"enabled": true,
"credentialPath": "~/.gmail-multi-mcp/accounts/work/credentials.json",
"tokenPath": "~/.gmail-multi-mcp/accounts/work/token.json"
}
]
}
## 铁路/SSE部署
此服务器可以作为stdio MCP或SSE支持的HTTP服务器运行。
- 集 `MCP_TRANSPORT=sse` 强制HTTP/SSE模式。
- 如果 `PORT` 如果存在,服务器会自动切换到SSE模式。
- SSE端点服务于 `/sse` 留言可在 `/messages`.
- 配置仍符合要求 `GMAILMCPCONFIG_DIR` 和 `GMAIL_MCP_CONFIG_DIR`.
对于铁路,将启动命令指向 `npm start` 或 `node dist/index.js` 让铁路提供 `PORT`.
## OAuth入职培训
直接通过MCP工具对帐户进行身份验证:
### 步骤1:启动身份验证
打电话给 `begin_account_auth` 使用OAuth凭据的工具:```typescript
{
"account_id": "personal",
"email": "user@gmail.com",
"credentials_json": {
"installed": {
"client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
"client_secret": "YOUR_CLIENT_SECRET",
"redirect_uris": ["http://localhost"]
}
}
}
或者使用文件路径:```typescript
{
"account_id": "personal",
"email": "user@gmail.com",
"credentials_path": "/path/to/credentials.json"
}
该工具返回一个Google OAuth URL。在浏览器中打开此URL。
### 步骤2:完成身份验证
1. 在浏览器中,使用Gmail帐户登录
1. 授予请求的权限
1. 谷歌将你重定向到一个本地主机URL `code` 参数
1. 从URL复制授权码
呼叫 `finish_account_auth`:```typescript
{
"account_id": "personal",
"authorization_code": "4/0AfJoh..."
}
您的帐户现在已通过身份验证,可以使用了。
使用示例
示例1:读取所有帐户的最近电子邮件```typescript
// Aggregates across all enabled accounts
{
"max_results": 20,
"include_body": true
}
// Returns emails with source account indicated
### 示例2:跨多个帐户搜索```typescript
{
"query": "from:boss@company.com is:unread",
"max_results": 10
}
// Searches all enabled accounts, merges and sorts results
示例3:从特定帐户发送电子邮件```typescript
{
"account": "work",
"to": "colleague@company.com",
"subject": "Project Update",
"body": "Here's the latest on the project...",
"html": false
}
### 示例4:从一个帐户只读```typescript
{
"account": "personal",
"max_results": 10,
"query": "label:important"
}
示例5:管理标签```typescript
// Create a new label
{
"account": "personal",
"name": "Urgent-2026"
}
// Add label to messages
{
"account": "personal",
"message_ids": ["msg123", "msg456"],
"label_ids": ["Label_789"]
}
### 示例6:删除草稿```typescript
// Delete one or more drafts by their draft IDs (returned by create_draft)
{
"account": "personal",
"draft_ids": ["r5457071851533655344", "r774137312565667821"]
}
API 参考
读取操作
list_accounts
返回所有已配置的帐户及其运行状况。
参数: 无
退货:```typescript
{
accounts: Array<{
id: string
email: string
displayName: string
enabled: boolean
hasValidToken: boolean
}>
}
#### `read_emails`
使用可选过滤功能获取最近的电子邮件。
**参数:**
- `account` (可选):要读取的帐户ID。省略汇总所有账户。
- `max_results` (可选,默认值:20):要返回的电子邮件数量(1-100)
- `query` (可选):Gmail搜索查询
- `include_body` (可选,默认值:false):包括明文正文提取
**退货:** 包含元数据、标题和可选正文的电子邮件对象数组
#### `search_emails`
使用Gmail查询语法搜索电子邮件。
**参数:**
- `query` (必填):Gmail搜索查询
- `account` (可选):要搜索的帐户ID。忽略搜索所有帐户。
- `max_results` (可选,默认值:25):最大结果(1-100)
**退货:** 匹配的电子邮件数组
#### `get_email_thread`
检索完整的电子邮件线索。
**参数:**
- `account` (必填):帐户ID
- `thread_id` (必填):Gmail线程ID
**退货:** 包含所有消息的线程对象
#### `get_labels`
列出帐户的所有标签。
**参数:**
- `account` (必填):帐户ID
**退货:** 带有ID和名称的标签对象数组
### 写入操作
#### `send_email`
从特定帐户发送电子邮件。
**参数:**
- `account` (必填):帐户ID
- `to` (必填):收件人电子邮件地址
- `subject` (必填):电子邮件主题
- `body` (必填):电子邮件正文
- `cc` (可选):CC收件人
- `bcc` (可选):BCC收件人
- `html` (可选,默认值:false):以HTML格式发送
- `attachments` (可选):本地文件附件数组。每个项目支持:
- `path` (必需):绝对或本地文件系统路径
- `filename` (可选):覆盖Gmail中显示的文件名
- `content_type` (可选):覆盖MIME类型,例如 `application/pdf`
**退货:** 已发送邮件详细信息
#### `create_draft`
创建电子邮件草稿。
**参数:** 同 `send_email`
**退货:** 草案细节包括 `draft_id` 和 `thread_id`
#### `delete_drafts`
永久删除一个或多个草稿。使用由返回的草稿ID `create_draft`注意:草稿ID与消息ID不同,不能与 `trash_emails`.
**参数:**
- `account` (必填):帐户ID
- `draft_ids` (必填):要删除的草稿ID数组
**退货:** 已删除草稿计数
#### `mark_as_read`
将邮件标记为已读。
**参数:**
- `account` (必填):帐户ID
- `message_ids` (必填):消息ID数组
#### `archive_emails`
存档邮件(删除收件箱标签)。
**参数:**
- `account` (必填):帐户ID
- `message_ids` (必填):消息ID数组
#### `trash_emails`
将邮件移至垃圾箱。
**参数:**
- `account` (必填):帐户ID
- `message_ids` (必填):消息ID数组
### 标签操作
#### `add_labels`
为邮件添加标签。
**参数:**
- `account` (必填):帐户ID
- `message_ids` (必填):消息ID数组
- `label_ids` (必填):标签ID数组
#### `remove_labels`
从邮件中删除标签。
**参数:**
- `account` (必填):帐户ID
- `message_ids` (必填):消息ID数组
- `label_ids` (必填):标签ID数组
#### `create_label`
创建一个新的Gmail标签。
**参数:**
- `account` (必填):帐户ID
- `name` (必填):标签名称
- `label_list_visibility` (可选,默认:“labelShow”)
- `message_list_visibility` (可选,默认:“show”)
#### `delete_label`
删除Gmail标签。
**参数:**
- `account` (必填):帐户ID
- `label_id` (必填):要删除的标签ID
## 故障排除
### “无效授权”错误
这通常意味着您的授权码已过期。授权码是一次性的,几分钟后过期。
**解决方案:** 跑 `begin_account_auth` 再次获取新的OAuth URL和授权码。
### “令牌已过期或被吊销”
您的刷新令牌不再有效。
**解决方案:**
1. 删除 `token.json` 受影响帐户的文件
1. 再次运行OAuth流(`begin_account_auth` 然后 `finish_account_auth`)
### “权限不足”
OAuth令牌没有所需的作用域。
**解决方案:**
1. 检查您的Google Cloud OAuth同意屏幕是否具有所有必需的范围
1. 重新运行OAuth流以授予新权限
1. 所需范围:
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/gmail.send`
- `https://www.googleapis.com/auth/userinfo.email`
### 未找到帐户
指定的帐户ID在中不存在 `accounts.json`.
**解决方案:**
1. 跑 `list_accounts` 查看可用帐户
1. 确保您完成了帐户的OAuth入职培训
1. 检查帐户是否 `enabled: true` 在 `accounts.json`
### 速率限制
Gmail API有费率限制(每日配额和每个用户配额)。
**解决方案:**
1. 查看您的配额 谷歌云控制台
1. 在应用程序中实现指数回退
1. 如有需要,考虑申请增加配额
## 贡献
欢迎捐款。方法如下:
1. 分叉存储库
1. 创建要素分支(`git checkout -b feature/your-feature`)
1. 提交您的更改(`git commit -m 'Add your feature'`)
1. 推到分支(`git push origin feature/your-feature`)
1. 打开拉取请求
### 开发脚本```bash
# Watch mode for development
npm run dev
# Type checking
npm run typecheck
# Build for production
npm run build
# Run the server
npm run start
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
- 与 模型上下文协议SDK
- 用途 谷歌API Node.js客户端
链接
- MCP文件
- Gmail API文档
- 问题和Bug报告
建造于 泰勒 萨卡奇
快速入门TL;博士```bash
npm install
npm run build
node dist/index.js
然后将服务器添加到MCP配置中,并在每个帐户上添加 `begin_account_auth` + `finish_account_auth`.
## 工作原理(TL;DR)
- 服务器在本地配置目录中存储帐户级凭据/令牌
- OAuth流通过MCP工具处理
- 读取/搜索可以聚合所有已启用的帐户
- Gmail API调用按所选帐户执行
## LLM快速复制
使用GitHub中此代码块上的复制按钮。```txt
Repo: gmail-multi-inbox-mcp
Goal: Multi-account Gmail MCP with built-in OAuth onboarding.
Setup:
1) npm install && npm run build
2) Add to MCP config
3) Run begin_account_auth + finish_account_auth for each inbox
Use:
- list_accounts to verify health
- read_emails/search_emails aggregated or per account
- send_email/create_draft/delete_drafts/label tools for write actions
How it works:
- Node MCP server maintains per-account token files and calls Gmail API
