Gmail 自动认证 MCP 服务器
一个用于在 Claude Desktop 中集成 Gmail 的模型上下文协议 (MCP) 服务器，并支持自动身份验证。该服务器使 AI 助手能够通过自然语言交互来管理 Gmail。
特征
- 发送包含主题、内容、附件和收件人的电子邮件
- 完全支持主题行和电子邮件内容中的国际字符
- 使用高级 MIME 结构处理按 ID 读取电子邮件消息
- 查看电子邮件附件信息（文件名、类型、大小）
- 使用各种条件（主题、发件人、日期范围）搜索电子邮件
- 全面的标签管理，能够创建、更新、删除和列出标签
- 列出所有可用的 Gmail 标签（系统和用户定义）
- 列出收件箱、已发送或自定义标签中的电子邮件
- 将电子邮件标记为已读/未读
- 将电子邮件移动到不同的标签/文件夹
- 删除电子邮件
- 批量操作可同时高效处理多封电子邮件
- 与 Gmail API 完全集成
- 具有自动浏览器启动功能的简单 OAuth2 身份验证流程
- 支持桌面和 Web 应用程序凭证
- 全球凭证存储，方便快捷
安装和认证
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装 Gmail AutoAuth：
npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude
手动安装
- 创建 Google Cloud 项目并获取凭据：a.创建 Google Cloud 项目：
b.创建 OAuth 2.0 凭证：
- 前往“API 和服务”>“凭证”
- 点击“创建凭证”>“OAuth 客户端 ID”
- 选择“桌面应用程序”或“Web 应用程序”作为应用程序类型
- 命名并点击“创建”
- 对于 Web 应用程序，将
http://localhost:3000/oauth2callback添加到授权重定向 URI - 下载客户端 OAuth 密钥的 JSON 文件
- 将密钥文件重命名为
gcp-oauth.keys.json
- 运行身份验证：您可以通过两种方式进行身份验证：a.全局认证（推荐）：
# First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/
# Run authentication from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth
# Place gcp-oauth.keys.json in your current directory
# The file will be automatically copied to global config
npx @gongrzhe/server-gmail-autoauth-mcp auth
- 在当前目录或
~/.gmail-mcp/中查找gcp-oauth.keys.json - 如果在当前目录中找到，则将其复制到
~/.gmail-mcp/ - 打开默认浏览器进行 Google 身份验证
- 将凭据保存为
~/.gmail-mcp/credentials.json
笔记：
- 身份验证成功后，凭据将全局存储在
~/.gmail-mcp/中，可从任何目录使用 - 支持桌面应用程序和 Web 应用程序凭据
- 对于 Web 应用程序凭证，请确保将
http://localhost:3000/oauth2callback添加到授权重定向 URI
- 在 Claude Desktop 中配置：
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
Docker 支持
如果您更喜欢使用 Docker：
- 验证：
docker run -i --rm \
--mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
-v mcp-gmail:/gmail-server \
-e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
-e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
-p 3000:3000 \
mcp/gmail auth
- 用法：
{
"mcpServers": {
"gmail": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"mcp-gmail:/gmail-server",
"-e",
"GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
"mcp/gmail"
]
}
}
}
云服务器认证
对于云服务器环境（如 n8n），您可以在身份验证期间指定自定义回调 URL：
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
云环境设置说明
- 配置反向代理：
- 设置 n8n 容器以公开用于身份验证的端口
- 配置反向代理，将来自您的域（例如
gmail.gongrzhe.com ）的流量转发到此端口
- DNS配置：
- 在您的 DNS 设置中添加 A 记录，以将您的域名解析为云服务器的 IP 地址
- Google云平台设置：
- 在您的 Google Cloud Console 中，将您的自定义域名回调 URL（例如
https://gmail.gongrzhe.com/oauth2callback ）添加到授权重定向 URI 列表
- 运行身份验证：
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
- 在您的应用程序中配置：
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
这种方法允许身份验证流程在无法访问本地主机的环境中正常工作，例如容器化应用程序或云服务器。
可用工具
服务器提供了以下可以通过Claude Desktop使用的工具：
1.发送电子邮件（ send_email ）
立即发送新电子邮件。
{
"to": ["recipient@example.com"],
"subject": "Meeting Tomorrow",
"body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
"cc": ["cc@example.com"],
"bcc": ["bcc@example.com"]
}
2. 草稿电子邮件（ draft_email ）
创建电子邮件草稿但不发送。
{
"to": ["recipient@example.com"],
"subject": "Draft Report",
"body": "Here's the draft report for your review.",
"cc": ["manager@example.com"]
}
3.阅读电子邮件（ read_email ）
通过 ID 检索特定电子邮件的内容。
{
"messageId": "182ab45cd67ef"
}
4. 搜索电子邮件（ search_emails ）
使用 Gmail 搜索语法搜索电子邮件。
{
"query": "from:sender@example.com after:2024/01/01 has:attachment",
"maxResults": 10
}
5.修改邮箱（ modify_email ）
在电子邮件中添加或删除标签（移动到不同的文件夹、存档等）。
{
"messageId": "182ab45cd67ef",
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"]
}
6.删除电子邮件（ delete_email ）
永久删除电子邮件。
{
"messageId": "182ab45cd67ef"
}
7. 列出电子邮件标签（ list_email_labels ）
检索所有可用的 Gmail 标签。
8.创建标签（ create_label ）
创建新的 Gmail 标签。
{
"name": "Important Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
9.更新标签（ update_label ）
更新现有的 Gmail 标签。
{
"id": "Label_1234567890",
"name": "Urgent Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
10.删除标签（ delete_label ）
删除 Gmail 标签。
{
"id": "Label_1234567890"
}
11. 获取或创建标签（ get_or_create_label ）
通过名称获取现有标签，如果不存在则创建它。
{
"name": "Project XYZ",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
12. 批量修改邮件（ batch_modify_emails ）
高效批量修改多封电子邮件的标签。
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"],
"batchSize": 50
}
13. 批量删除邮件（ batch_delete_emails ）
高效地批量永久删除多封电子邮件。
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"batchSize": 50
}
高级搜索语法
search_emails工具支持 Gmail 强大的搜索运算符：
| 操作员 | 例子 | 描述 |
|---|
from: | from:john@example.com | 来自特定发件人的电子邮件 |
to: | to:mary@example.com | 发送给特定收件人的电子邮件 |
subject: | subject:"meeting notes" | 主题中包含特定文本的电子邮件 |
has:attachment | has:attachment | 带附件的电子邮件 |
after: | after:2024/01/01 | 某个日期之后收到的电子邮件 |
before: | before:2024/02/01 | 某个日期之前收到的电子邮件 |
is: | is:unread | 具有特定状态的电子邮件 |
label: | label:work | 带有特定标签的电子邮件 |
您可以组合多个运算符： from:john@example.com after:2024/01/01 has:attachment
高级功能
电子邮件内容提取
服务器智能地从复杂的 MIME 结构中提取电子邮件内容：
- 优先考虑纯文本内容（如有）
- 如果纯文本不可用，则返回 HTML 内容
- 处理具有嵌套部分的多部分 MIME 消息
- 处理附件信息（文件名、类型、大小）
- 保留原始电子邮件标题（发件人、收件人、主题、日期）
国际角色支持
服务器完全支持电子邮件主题和内容中的非 ASCII 字符，包括：
- 土耳其语、中文、日语、韩语和其他非拉丁字母
- 特殊字符和符号
- 正确的编码确保在电子邮件客户端中正确显示
全面的标签管理
该服务器提供了一套完整的用于管理 Gmail 标签的工具：
- 创建标签：创建具有可自定义可见性设置的新标签
- 更新标签：重命名标签或更改其可见性设置
- 删除标签：删除用户创建的标签（系统标签受保护）
- 查找或创建：按名称获取标签，如果未找到则自动创建
- 列出所有标签：查看所有系统和用户标签的详细信息
- 标签可见性选项：控制标签在消息和标签列表中的显示方式
标签可见性设置包括：
messageListVisibility ：控制标签是否出现在消息列表中（ show或hide ）labelListVisibility ：控制标签在标签列表中的显示方式（ labelShow 、 labelShowIfUnread或labelHide ）
这些标签管理功能可以直接通过 Claude 对电子邮件进行复杂的组织，而无需切换到 Gmail 界面。
批量操作
该服务器包括高效的批处理功能：
- 一次处理最多 50 封电子邮件（可配置批量大小）
- 自动对大型电子邮件集进行分块以避免 API 限制
- 每个操作的详细成功/失败报告
- 通过单独重试实现优雅的错误处理
- 非常适合批量收件箱管理和组织任务
安全说明
- OAuth 凭据安全地存储在您的本地环境中（
~/.gmail-mcp/ ） - 服务器使用离线访问来维持持久身份验证
- 切勿共享或提交您的凭据以进行版本控制
- 定期检查并撤销 Google 帐户设置中未使用的访问权限
- 凭证存储在全局，但只有当前用户才能访问
故障排除
- 未找到 OAuth 密钥
- 确保
gcp-oauth.keys.json位于当前目录或~/.gmail-mcp/ - 检查文件权限
- 凭证格式无效
- 确保您的 OAuth 密钥文件包含
web或installed凭据 - 对于 Web 应用程序，验证重定向 URI 是否配置正确
- 端口已被使用
- 如果端口 3000 已被使用，请在运行身份验证之前释放它
- 您可以找到并停止使用该端口的进程
- 批量操作失败
- 如果批量操作失败，它们会自动重试单个项目
- 检查具体失败的详细错误消息
- 如果遇到速率限制，请考虑减少批次大小
贡献
欢迎贡献代码！欢迎提交 Pull 请求。
运行评估
evals 包会加载一个 mcp 客户端，然后运行 index.ts 文件，因此测试之间无需重新构建。您可以通过在 npx 命令前添加前缀来加载环境变量。完整文档可在此处找到。
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
执照
麻省理工学院
支持
如果您遇到任何问题或有疑问，请在 GitHub 存储库上提交问题。