Gmail多收件箱MCP服务器

一个模型上下文协议（MCP）服务器，使AI助手能够通过内置的OAuth身份验证同时管理多个Gmail帐户。

![License: MIT](https://opensource.org/licenses/MIT) ](https://nodejs.org/) ![TypeScript](https://www.typescriptlang.org/)

为什么选择MCP服务器？

与现有的Gmail MCP服务器不同，此实现提供了：

多账户支持：从单个MCP服务器实例管理多个Gmail帐户
智能聚合：同时读取和搜索所有帐户
内置OAuth流：通过MCP工具完成身份验证设置-无需手动生成令牌
类型安全：使用TypeScript构建，具有可靠性和更好的IDE支持
自动令牌刷新：自动处理令牌过期并保存刷新的令牌
综合API：完整的Gmail 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凭据 （桌面应用程序类型）

安装

# 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.创建谷歌云项目

首选谷歌云控制台
创建新项目或选择现有项目
记下您的项目ID

2.启用Gmail API

在您的项目中，请访问 API和服务 > 图书馆
搜索“Gmail API”
点击启用

3.创建OAuth 2.0凭据

首选 API和服务 > 凭证
点击 +创建凭据 > OAuth客户端ID
如果出现提示，请配置OAuth同意屏幕：

- 选择“外部”用户类型 - 填写必填字段（应用程序名称、支持电子邮件） - 将您的电子邮件添加到测试用户

对于应用程序类型，选择 桌面应用
为其命名（例如，“Gmail MCP客户端”）
点击创建
下载JSON文件 -你需要这个进行身份验证

4.OAuth同意屏幕设置

首选 API和服务 > OAuth 同意屏幕
添加以下范围：

- https://www.googleapis.com/auth/gmail.modify - https://www.googleapis.com/auth/gmail.send - https://www.googleapis.com/auth/userinfo.email

将您的Gmail地址添加为测试用户

配置

添加到您的MCP设置

将此服务器添加到您的 .mcp.json 配置文件（调整路径以匹配您的安装）：

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": [
        "/path/to/gmail-multi-inbox-mcp/dist/index.js"
      ]
    }
  }
}

自定义配置目录（可选）

要使用自定义目录存储帐户数据，请执行以下操作：

{
  "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格式

{
  "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凭据的工具：

{
  "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"]
    }
  }
}

或者使用文件路径：

{
  "account_id": "personal",
  "email": "user@gmail.com",
  "credentials_path": "/path/to/credentials.json"
}

该工具返回一个Google OAuth URL。在浏览器中打开此URL。

步骤2：完成身份验证

在浏览器中，使用Gmail帐户登录
授予请求的权限
谷歌将你重定向到一个本地主机URL code 参数
从URL复制授权码

呼叫 finish_account_auth:

{
  "account_id": "personal",
  "authorization_code": "4/0AfJoh..."
}

您的帐户现在已通过身份验证，可以使用了。

使用示例

示例1：读取所有帐户的最近电子邮件

// Aggregates across all enabled accounts
{
  "max_results": 20,
  "include_body": true
}

// Returns emails with source account indicated

示例2：跨多个帐户搜索

{
  "query": "from:boss@company.com is:unread",
  "max_results": 10
}

// Searches all enabled accounts, merges and sorts results

示例3：从特定帐户发送电子邮件

{
  "account": "work",
  "to": "colleague@company.com",
  "subject": "Project Update",
  "body": "Here's the latest on the project...",
  "html": false
}

示例4：从一个帐户只读

{
  "account": "personal",
  "max_results": 10,
  "query": "label:important"
}

示例5：管理标签

// Create a new label
{
  "account": "personal",
  "name": "Urgent-2026"
}

// Add label to messages
{
  "account": "personal",
  "message_ids": ["msg123", "msg456"],
  "label_ids": ["Label_789"]
}

示例6：删除草稿

// Delete one or more drafts by their draft IDs (returned by create_draft)
{
  "account": "personal",
  "draft_ids": ["r5457071851533655344", "r774137312565667821"]
}

API 参考

读取操作

`list_accounts`

返回所有已配置的帐户及其运行状况。

参数： 无

退货：

{
  accounts: Array
}

`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和授权码。

“令牌已过期或被吊销”

您的刷新令牌不再有效。

解决方案：

删除 token.json 受影响帐户的文件
再次运行OAuth流(begin_account_auth 然后 finish_account_auth)

“权限不足”

OAuth令牌没有所需的作用域。

解决方案：

检查您的Google Cloud OAuth同意屏幕是否具有所有必需的范围
重新运行OAuth流以授予新权限
所需范围：

- https://www.googleapis.com/auth/gmail.modify - https://www.googleapis.com/auth/gmail.send - https://www.googleapis.com/auth/userinfo.email

未找到帐户

指定的帐户ID在中不存在 accounts.json.

解决方案：

跑 list_accounts 查看可用帐户
确保您完成了帐户的OAuth入职培训
检查帐户是否 enabled: true 在 accounts.json

速率限制

Gmail API有费率限制（每日配额和每个用户配额）。

解决方案：

查看您的配额谷歌云控制台
在应用程序中实现指数回退
如有需要，考虑申请增加配额

贡献

欢迎捐款。方法如下：

分叉存储库
创建要素分支(git checkout -b feature/your-feature)
提交您的更改(git commit -m 'Add your feature')
推到分支(git push origin feature/your-feature)
打开拉取请求

开发脚本

# 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
用途

链接

______________________________________________________________________

建造于泰勒萨卡奇

快速入门TL；博士

npm install
npm run build
node dist/index.js

然后将服务器添加到MCP配置中，并在每个帐户上添加 begin_account_auth + finish_account_auth.

工作原理（TL；DR）

服务器在本地配置目录中存储帐户级凭据/令牌
OAuth流通过MCP工具处理
读取/搜索可以聚合所有已启用的帐户
Gmail API调用按所选帐户执行

LLM快速复制

使用GitHub中此代码块上的复制按钮。

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

Gmail Multi Inbox MCP

快速接入

详细介绍

Gmail多收件箱MCP服务器

为什么选择MCP服务器？

目录

特性

读取操作

写入操作

标签管理

账户管理

先决条件

安装

谷歌云设置

1.创建谷歌云项目

2.启用Gmail API

3.创建OAuth 2.0凭据

4.OAuth同意屏幕设置

配置

添加到您的MCP设置

自定义配置目录（可选）

目录结构

accounts.json格式

铁路/SSE部署

OAuth入职培训

步骤1：启动身份验证

步骤2：完成身份验证

使用示例

示例1：读取所有帐户的最近电子邮件

示例2：跨多个帐户搜索

示例3：从特定帐户发送电子邮件

示例4：从一个帐户只读

示例5：管理标签

示例6：删除草稿

API 参考

读取操作

list_accounts

read_emails

search_emails

get_email_thread

get_labels

写入操作

send_email

create_draft

delete_drafts

mark_as_read

archive_emails

trash_emails

标签操作

add_labels

remove_labels

create_label

delete_label

故障排除

“无效授权”错误

“令牌已过期或被吊销”

“权限不足”

未找到帐户

速率限制

贡献

开发脚本

许可证

致谢

链接

快速入门TL；博士

工作原理（TL；DR）

LLM快速复制

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`list_accounts`

`read_emails`

`search_emails`

`get_email_thread`

`get_labels`

`send_email`

`create_draft`

`delete_drafts`

`mark_as_read`

`archive_emails`

`trash_emails`

`add_labels`

`remove_labels`

`create_label`

`delete_label`