Server Gmail MCP

Gmail AutoAuth MCP服务器（主动维护分叉）


这是一个积极维护的叉子 共和/Gmail MCP服务器. 自2025年8月以来，原始存储库一直处于未维护状态——7个多月以来，维护人员活动为零，72多个未合并的拉取请求。我每天都在使用这个MCP服务器，作为我的Claude Code工作流程的一部分，并依赖于它的正常工作，所以我拿起了它。 欢迎拉取请求。 如果你一直在做修复或功能，却没有地方提交，那么这里就是你的地方。

这个叉子增加了什么

• 修复了回复线程 --自动解析 In-Reply-To 和 References 邮件头使电子邮件回复落在正确的线程中，而不是创建孤立的邮件(上游PR#91，仍待定）
• 作为别名支持发送 --可选 from 多身份电子邮件管理参数（从任何配置的Gmail别名发送）
• 螺纹级工具 — get_thread, list_inbox_threads, get_inbox_with_threads 在一次调用中高效地读取基于线程的电子邮件

所有功能都在日常使用中经过生产测试。


______________________________________________________________________

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


特性

• 发送主题、内容、， 附件，以及收件人
• 完全附件支持 -发送和接收文件附件
• 下载电子邮件附件 到本地文件系统
• 下载完整电子邮件 转换为json/eml/txt/html格式的文件
• 线程级操作 --获取完整线程、列出收件箱线程、批量扩展线程
• 支持HTML电子邮件和HTML和纯文本版本的多部分消息
• 完全支持主题行和电子邮件内容中的国际字符
• 通过高级MIME结构处理按ID读取电子邮件
• 增强的附件显示 显示文件名、类型、大小和下载ID
• 使用各种条件（主题、发件人、日期范围）搜索电子邮件
• 全面的标签管理，能够创建、更新、删除和列出标签
• 列出所有可用的Gmail标签（系统和用户定义）
• 在收件箱、已发送或自定义标签中列出电子邮件
• 将电子邮件标记为已读/未读
• 将电子邮件移动到不同的标签/文件夹
• 删除电子邮件
• 批量操作，可同时高效处理多封电子邮件
• 与Gmail API完全集成
• 具有自动浏览器启动功能的简单OAuth2身份验证流程
• 支持桌面和Web应用程序凭据
• 全球凭证存储，方便使用

安装和身份验证

手动安装

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"
         ]
       }
     }
   }

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

OAuth 授权范围

您可以通过在身份验证期间指定OAuth作用域来限制服务器的Gmail访问。这控制了LLM可用的工具，减少了敏感操作的攻击面。

可用范围

备注: gmail.modify 是一个包含所有读取功能的超集。你不需要 gmail.readonly 如果你有 gmail.modify.

使用特定范围进行身份验证

使用 --scopes 标记以仅请求所需的权限：

# Read-only access (recommended for safe browsing)
npx @gongrzhe/server-gmail-autoauth-mcp auth --scopes=gmail.readonly

# Read-only with filter management
npx @gongrzhe/server-gmail-autoauth-mcp auth --scopes=gmail.readonly,gmail.settings.basic

# Full access (default behavior)
npx @gongrzhe/server-gmail-autoauth-mcp auth --scopes=gmail.modify,gmail.settings.basic

如果没有 --scopes 如果提供了标志，服务器默认为 gmail.modify,gmail.settings.basic 为了实现完整的功能。

范围到工具映射

服务器会根据您的授权范围自动筛选可用工具：

重新验证

要更改作用域，只需使用不同的作用域再次运行auth命令。这将替换您现有的凭据。

Claude代码CLI配置

使用此MCP服务器 克劳德代码，将其添加到MCP设置中。

只读配置（建议用于安全浏览）

首先，使用只读作用域进行身份验证：

npx @gongrzhe/server-gmail-autoauth-mcp auth --scopes=gmail.readonly

然后添加到您的Claude Code MCP设置中(~/.claude/mcp_settings.json 或项目级别 .mcp.json):

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

对于只读作用域，只有这4个工具可供Claude使用：

• read_email -阅读电子邮件内容
• search_emails -搜索收件箱
• list_email_labels -列出可用标签
• download_attachment -下载附件

完全访问配置

要获得完整的Gmail管理功能：

npx @gongrzhe/server-gmail-autoauth-mcp auth --scopes=gmail.modify,gmail.settings.basic

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

这启用了所有20个工具，包括发送电子邮件、管理标签、创建过滤器、全部回复和批处理操作。

可用工具

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

1.发送电子邮件(send_email)

立即发送一封新电子邮件。支持纯文本、HTML或多部分电子邮件 带有可选文件附件.

基本电子邮件：

{
  "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"],
  "mimeType": "text/plain"
}

带附件的电子邮件：

{
  "to": ["recipient@example.com"],
  "subject": "Project Files",
  "body": "Hi,\n\nPlease find the project files attached.\n\nBest regards",
  "attachments": [
    "/path/to/document.pdf",
    "/path/to/spreadsheet.xlsx",
    "/path/to/presentation.pptx"
  ]
}

HTML电子邮件示例：

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "mimeType": "text/html",
  "body": "
Meeting Reminder

Just a reminder about our meeting tomorrow at 10 AM.

Best regards
"
}

多部分电子邮件示例（HTML+纯文本）：

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "mimeType": "multipart/alternative",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "htmlBody": "
Meeting Reminder

Just a reminder about our meeting tomorrow at 10 AM.

Best regards
"
}

2.电子邮件草稿(draft_email)

创建电子邮件草稿而不发送。 还支持附件.

{
  "to": ["recipient@example.com"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["manager@example.com"],
  "attachments": ["/path/to/draft_report.docx"]
}

3.阅读电子邮件(read_email)

通过特定电子邮件的ID检索其内容。 现在显示增强的附件信息.

{
  "messageId": "182ab45cd67ef"
}

增强响应包括附件详细信息：

Subject: Project Files
From: sender@example.com
To: recipient@example.com
Date: Thu, 19 Jun 2025 10:30:00 -0400

Email body content here...

Attachments (2):
- document.pdf (application/pdf, 245 KB, ID: ANGjdJ9fkTs-i3GCQo5o97f_itG...)
- spreadsheet.xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 89 KB, ID: BWHkeL8gkUt-j4HDRp6o98g_juI...)

4. 下载附件(download_attachment)

新：将电子邮件附件下载到本地文件系统。

{
  "messageId": "182ab45cd67ef",
  "attachmentId": "ANGjdJ9fkTs-i3GCQo5o97f_itG...",
  "savePath": "/path/to/downloads",
  "filename": "downloaded_document.pdf"
}

参数：

• messageId：包含附件的电子邮件的ID
• attachmentId：附件ID（显示在增强的电子邮件显示中）
• savePath：保存文件的目录（可选，默认为当前目录）
• filename：自定义文件名（可选，如果未提供，则使用原始文件名）

5.搜索电子邮件(search_emails)

使用Gmail搜索语法搜索电子邮件。

{
  "query": "from:sender@example.com after:2024/01/01 has:attachment",
  "maxResults": 10
}

6.修改电子邮件(modify_email)

添加或删除电子邮件中的标签（移动到不同的文件夹、存档等）。

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

7.删除电子邮件(delete_email)

永久删除电子邮件。

{
  "messageId": "182ab45cd67ef"
}

8.列出电子邮件标签(list_email_labels)

检索所有可用的Gmail标签。

{}

9.创建标签(create_label)

创建新的Gmail标签。

{
  "name": "Important Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10.更新标签(update_label)

更新现有的Gmail标签。

{
  "id": "Label_1234567890",
  "name": "Urgent Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

11.删除标签(delete_label)

删除Gmail标签。

{
  "id": "Label_1234567890"
}

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

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

{
  "name": "Project XYZ",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

13.批量修改电子邮件(batch_modify_emails)

以高效的批处理方式修改多封电子邮件的标签。

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"],
  "batchSize": 50
}

14.批量删除电子邮件(batch_delete_emails)

高效批量永久删除多封电子邮件。

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

15.创建筛选器(create_filter)

使用自定义条件和操作创建新的Gmail筛选器。

{
  "criteria": {
    "from": "newsletter@company.com",
    "hasAttachment": false
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

16.列出过滤器(list_filters)

检索所有Gmail过滤器。

{}

17.获取过滤器(get_filter)

获取特定Gmail过滤器的详细信息。

{
  "filterId": "ANe1Bmj1234567890"
}

18.删除筛选器(delete_filter)

删除Gmail筛选器。

{
  "filterId": "ANe1Bmj1234567890"
}

19.从模板创建筛选器(create_filter_from_template)

使用预定义的模板为常见场景创建过滤器。

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "notifications@github.com",
    "labelIds": ["Label_GitHub"],
    "archive": true
  }
}

20.全部回复(reply_all)

回复电子邮件的所有收件人。自动获取原始电子邮件以构建收件人列表，并设置适当的线程头(In-Reply-To, References, threadId).

它是如何工作的：

1. 通过以下方式获取原始电子邮件 messageId
2. 构建 到 来自原始发件人（发件人标头）
3. 构建 CC 来自原始To+CC，不包括您自己的电子邮件
4. 设置线程头，以便回复到达正确的线程
5. 通过现有发送 send_email 管道（支持附件、HTML、多部分）

{
  "messageId": "182ab45cd67ef",
  "body": "Thanks for the update, everyone. I'll review and get back to you.",
  "mimeType": "text/plain"
}

使用HTML和附件：

{
  "messageId": "182ab45cd67ef",
  "body": "Plain text fallback",
  "htmlBody": "
Thanks for the update. See attached notes.
",
  "mimeType": "multipart/alternative",
  "attachments": ["/path/to/notes.pdf"]
}

参数：

• messageId （必填）：要回复的电子邮件的ID
• body （必填）：回复正文（纯文本，或使用多部分时回退）
• htmlBody （可选）：回复正文的HTML版本
• mimeType （可选）： text/plain （默认）， text/html，或 multipart/alternative
• attachments （可选）：要附加的文件路径数组

筛选器管理功能

筛选条件

您可以根据各种条件创建筛选器：

筛选器操作

筛选器可以执行以下操作：

筛选器模板

服务器包括用于常见过滤场景的预构建模板：

1.发件人模板(fromSender)

过滤来自特定发件人的电子邮件，并可选择将其存档。

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "newsletter@company.com",
    "labelIds": ["Label_Newsletter"],
    "archive": true
  }
}

2.主题过滤器模板(withSubject)

过滤具有特定主题文本的电子邮件，并可选择标记为已读。

{
  "template": "withSubject",
  "parameters": {
    "subjectText": "[URGENT]",
    "labelIds": ["Label_Urgent"],
    "markAsRead": false
  }
}

3.附件过滤模板(withAttachments)

过滤所有带附件的电子邮件。

{
  "template": "withAttachments",
  "parameters": {
    "labelIds": ["Label_Attachments"]
  }
}

4.大型电子邮件模板(largeEmails)

过滤大于指定大小的电子邮件。

{
  "template": "largeEmails",
  "parameters": {
    "sizeInBytes": 10485760,
    "labelIds": ["Label_Large"]
  }
}

5.内容过滤器模板(containingText)

过滤包含特定文本的电子邮件，并可选择标记为重要。

{
  "template": "containingText",
  "parameters": {
    "searchText": "invoice",
    "labelIds": ["Label_Finance"],
    "markImportant": true
  }
}

6.邮件列表模板(mailingList)

过滤邮件列表电子邮件，并可选择将其存档。

{
  "template": "mailingList",
  "parameters": {
    "listIdentifier": "dev-team",
    "labelIds": ["Label_DevTeam"],
    "archive": true
  }
}

常见过滤器示例

以下是一些实用的过滤器示例：

自动组织时事通讯：

{
  "criteria": {
    "from": "newsletter@company.com"
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

处理促销电子邮件：

{
  "criteria": {
    "query": "unsubscribe OR promotional"
  },
  "action": {
    "addLabelIds": ["Label_Promotions"],
    "removeLabelIds": ["INBOX", "UNREAD"]
  }
}

老板的优先电子邮件：

{
  "criteria": {
    "from": "boss@company.com"
  },
  "action": {
    "addLabelIds": ["IMPORTANT", "Label_Boss"]
  }
}

大型附件：

{
  "criteria": {
    "size": 10485760,
    "sizeComparison": "larger",
    "hasAttachment": true
  },
  "action": {
    "addLabelIds": ["Label_LargeFiles"]
  }
}

高级搜索语法

这 search_emails 该工具支持Gmail强大的搜索运营商：

您可以组合多个运算符： from:john@example.com after:2024/01/01 has:attachment

高级功能

电子邮件附件支持

服务器提供全面的附件功能：

• 发送附件：在中包含文件路径 attachments 发送或起草电子邮件时使用数组
• 附件检测：自动检测MIME类型和文件大小
• 下载能力：将任何电子邮件附件下载到本地文件系统
• 增强型显示器：查看详细的附件信息，包括文件名、类型、大小和下载ID
• 多种格式：支持所有常见文件类型（文档、图像、档案等）
• RFC822合规性：使用Nodemailer进行正确的MIME消息格式设置

支持的文件类型：所有标准文件类型，包括PDF、DOCX、XLSX、PPTX、图像（PNG、JPG、GIF）、存档（ZIP、RAR）等。

电子邮件内容提取

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

• 在可用时优先考虑纯文本内容
• 如果纯文本不可用，则回退到HTML内容
• 处理具有嵌套部分的多部分MIME消息
• 处理附件信息（文件名、类型、大小、下载ID）
• 保留原始电子邮件标题（发件人、收件人、主题、日期）

国际角色支持

服务器完全支持电子邮件主题和内容中的非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. 批量操作失败

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

1. 附件问题

- 文件未找到：确保附件文件路径正确且可访问 - 权限错误：检查服务器是否具有对附件文件的读取权限 - 大小限制：Gmail每封电子邮件的附件大小限制为25MB - 下载失败：验证您是否具有下载目录的写入权限

贡献

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

CI需要README更新 --每一次推动 main 每个PR都必须包含README.md更改（甚至是版本升级或更改日志条目）。这确保了文档在代码库发展时保持最新。

要绕过真正不需要文档更新的提交（依赖性颠簸、CI配置更改），请包括 [skip-readme] 或 [no-readme] 在您的提交消息或PR标题中。

运行评估

evals包加载一个mcp客户端，然后运行index.ts文件，因此不需要在测试之间重建。您可以通过在npx命令前加前缀来加载环境变量。可以找到完整的文档 这里.

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts

许可证

麻省理工学院

支持

如果您遇到任何问题或有疑问，请 提交问题.