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 项目：
- 前往Google Cloud Console
- 创建新项目或选择现有项目
- 为您的项目启用 Gmail API
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
b. 本地身份验证：
# 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 请求。

执照

麻省理工学院

支持

如果您遇到任何问题或有疑问，请在 GitHub 存储库上提交问题。

Integrations