Gmail AutoAuth MCP 服务器

用于 Claude Desktop 中的 Gmail 集成的 Model Context Protocol (MCP) 服务器，支持自动身份验证。该服务器使 AI 助手能够通过自然语言交互来管理 Gmail。

功能

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

安装与认证

通过 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 控制台
   • 创建新项目或选择现有项目
   • 为您的项目启用 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

1. 使用方法:

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-gmail:/gmail-server",
        "-e",
        "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
        "mcp/gmail"
      ]
    }
  }
}

可用工具

服务器提供了以下可通过 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 标签。

{}

高级搜索语法

search_emails 工具支持 Gmail 强大的搜索操作符：

您可以组合使用多个操作符：from:john@example.com after:2024/01/01 has:attachment

高级功能

邮件内容提取

服务器智能地从复杂的MIME结构中提取邮件内容：

• 当可用时优先选择纯文本内容
• 如果没有纯文本，则退回到HTML内容
• 处理带有嵌套部分的多部分MIME消息
• 处理附件信息（文件名、类型、大小）
• 保留原始邮件头（发件人、收件人、主题、日期）

国际字符支持

服务器完全支持邮件主题和内容中的非ASCII字符，包括：

• 土耳其语、中文、日文、韩文及其他非拉丁字母
• 特殊字符和符号
• 正确的编码确保在电子邮件客户端中正确显示

安全注意事项

• OAuth凭证安全地存储在您的本地环境 (~/.gmail-mcp/) 中
• 服务器使用离线访问以保持持久的身份验证
• 切勿共享或提交您的凭证到版本控制系统
• 定期审查并在Google帐户设置中撤销未使用的访问权限
• 凭证是全局存储的，但仅当前用户可访问

故障排除

1. 找不到OAuth密钥

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

2. 无效的凭证格式

   • 确保证书文件中包含web或installed类型的证书
   • 对于Web应用程序，请验证重定向URI是否已正确配置

3. 端口已被占用

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

贡献

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

许可证

MIT

支持

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