Gmail AutoAuth MCP 服务器

一个用于 Claude Desktop 中 Gmail 集成的模型上下文协议 (MCP) 服务器，支持自动身份验证。该服务器使 AI 助手能够通过自然语言交互来管理 Gmail。

功能

• 发送带有主题、内容、附件和收件人的电子邮件
• 完全支持主题行和电子邮件内容中的国际字符
• 通过 ID 读取电子邮件，并具有高级 MIME 结构处理能力
• 查看电子邮件附件信息（文件名、类型、大小）
• 使用各种条件（主题、发件人、日期范围）搜索电子邮件
• 全面的标签管理，能够创建、更新、删除和列出标签
• 列出所有可用的 Gmail 标签（系统和用户定义的）
• 列出收件箱、已发送或自定义标签中的电子邮件
• 将电子邮件标记为已读/未读
• 将电子邮件移动到不同的标签/文件夹
• 删除电子邮件
• 批量操作，可有效处理多个电子邮件
• 与 Gmail API 完全集成
• 简单的 OAuth2 身份验证流程，支持自动浏览器启动
• 支持桌面和 Web 应用程序凭据
• 全局凭据存储，方便使用

安装与身份验证

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Gmail AutoAuth：

npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

手动安装

1. 创建一个 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

2. 运行身份验证：

   您可以通过两种方式进行身份验证：

   a. 全局身份验证（推荐）：

   # 首次：将 gcp-oauth.keys.json 放置在您主目录的 .gmail-mcp 文件夹中
   mkdir -p ~/.gmail-mcp
   mv gcp-oauth.keys.json ~/.gmail-mcp/
   
   # 从任何地方运行身份验证
   npx @gongrzhe/server-gmail-autoauth-mcp auth
   

   b. 本地身份验证：

   # 将 gcp-oauth.keys.json 放置在当前目录中
   # 该文件将自动复制到全局配置
   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

3. 在 Claude Desktop 中配置：

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-gmail-autoauth-mcp"
      ]
    }
  }
}

Docker 支持

如果您更喜欢使用 Docker：

1. 身份验证：

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

2. 用法：

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

云环境设置说明

1. 配置反向代理：

   • 设置您的 n8n 容器以公开一个用于身份验证的端口
   • 配置反向代理以将来自您的域（例如，gmail.gongrzhe.com）的流量转发到此端口

2. DNS 配置：

   • 在您的 DNS 设置中添加一个 A 记录，以将您的域解析为您的云服务器的 IP 地址

3. Google Cloud Platform 设置：

   • 在您的 Google Cloud Console 中，将您的自定义域回调 URL（例如，https://gmail.gongrzhe.com/oauth2callback）添加到授权的重定向 URI 列表中

4. 运行身份验证：

   npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
   

5. 在您的应用程序中配置：

   {
     "mcpServers": {
       "gmail": {
         "command": "npx",
         "args": [
           "@gongrzhe/server-gmail-autoauth-mcp"
         ]
       }
     }
   }
   

这种方法允许身份验证流程在无法访问 localhost 的环境中正常工作，例如容器化应用程序或云服务器。

可用工具

该服务器提供以下可以通过 Claude Desktop 使用的工具：

1. 发送电子邮件 (send_email)

立即发送一封新电子邮件。

{
  "to": ["recipient@example.com"],
  "subject": "明天的会议",
  "body": "您好，\n\n只是提醒您明天上午 10 点的会议。\n\n此致",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"]
}

2. 草拟电子邮件 (draft_email)

创建一个草稿电子邮件，但不发送它。

{
  "to": ["recipient@example.com"],
  "subject": "草稿报告",
  "body": "这是供您审核的草稿报告。",
  "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": "重要项目",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

9. 更新标签 (update_label)

更新现有的 Gmail 标签。

{
  "id": "Label_1234567890",
  "name": "紧急项目",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10. 删除标签 (delete_label)

删除一个 Gmail 标签。

{
  "id": "Label_1234567890"
}

11. 获取或创建标签 (get_or_create_label)

按名称获取现有标签，如果不存在则创建它。

{
  "name": "项目 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:"会议记录"	主题中包含特定文本的电子邮件
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 帐户设置中未使用的访问权限
• 凭据全局存储，但只有当前用户可以访问

故障排除

1. 未找到 OAuth 密钥

   • 确保 gcp-oauth.keys.json 位于您的当前目录或 ~/.gmail-mcp/ 中
   • 检查文件权限

2. 无效的凭据格式

   • 确保您的 OAuth 密钥文件包含 web 或 installed 凭据
   • 对于 Web 应用程序，请验证重定向 URI 是否已正确配置

3. 端口已被使用

   • 如果端口 3000 已被使用，请在运行身份验证之前释放它
   • 您可以使用该端口查找并停止该进程

4. 批量操作失败

   • 如果批量操作失败，它们会自动重试单个项目
   • 检查详细的错误消息以获取特定失败
   • 如果遇到速率限制，请考虑减小批处理大小

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT

支持

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