MCP Gmail Setup

Gmail自动认证MCP服务器

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

 ](https://smithery.ai/server/@gongrzhe/server-gmail-autoauth-mcp)

特性

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

安装和身份验证

通过Smithery安装

通过以下方式自动安装Gmail AutoAuth for Claude Desktop 铁匠铺:

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

手动安装

1. 创建Google Cloud项目并获取凭据：

a.创建谷歌云项目：

- 首选 谷歌云控制台 - 创建新项目或选择现有项目 - 为您的项目启用Gmail API

b.创建OAuth 2.0凭据：

- 转到“API和服务”>“凭据” - 点击“创建凭据”>“OAuth客户端ID” - 选择“桌面应用程序”或“Web应用程序”作为应用程序类型 - 给它起个名字，然后单击“创建” - 对于Web应用程序，添加 http://localhost:3000/oauth2callback 到授权的重定向URI - 下载客户端OAuth密钥的JSON文件 - 将密钥文件重命名为 gcp-oauth.keys.json

1. 运行身份验证：

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

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

身份验证过程将：

- 寻找 gcp-oauth.keys.json 在当前目录或 ~/.gmail-mcp/ - 如果在当前目录中找到，请将其复制到 ~/.gmail-mcp/ - 打开默认浏览器进行谷歌身份验证 - 将凭据另存为 ~/.gmail-mcp/credentials.json

> 备注: > > - 成功身份验证后，凭据将全局存储在 ~/.gmail-mcp/ 并且可以从任何目录中使用 > - 支持桌面应用程序和Web应用程序凭据 > - 对于Web应用程序凭据，请确保添加 http://localhost:3000/oauth2callback 到您授权的重定向URI

1. 在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"
      ]
    }
  }
}

云服务器身份验证

对于云服务器环境（如n8n），您可以在身份验证期间指定自定义回调URL：

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

云环境设置说明

1. 配置反向代理：

- 设置n8n容器以暴露用于身份验证的端口 - 配置反向代理以转发来自您域的流量（例如。， gmail.gongrzhe.com)到这个港口

1. DNS配置：

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

1. 谷歌云平台设置：

- 在您的Google Cloud控制台中，添加您的自定义域回调URL（例如。， https://gmail.gongrzhe.com/oauth2callback)到授权重定向URI列表

1. 运行身份验证：

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

1. 在应用程序中配置：

   {
     "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: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/ - 检查文件权限

1. 凭据格式无效

- 确保您的OAuth密钥文件包含以下内容之一 web 或 installed 凭证 - 对于web应用程序，请验证重定向URI是否配置正确

1. 端口已在使用中

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

1. 批量操作失败

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

贡献

欢迎投稿！请随时提交拉取请求。

许可证

麻省理工学院

支持

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