AI导哈

Gmail自动化管理服务

一个支持自动认证的Gmail集成服务，通过自然语言交互帮助AI助手管理Gmail邮件、标签和附件。

  • by GongRzhe
  • JavaScript
  • 本地部署
  • 1169 星标
  • 更新于
在 GitHub 查看 GongRzhe/Gmail-MCP-Server

使用说明

Gmail AutoAuth MCP 服务器

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

特性

  • 发送主题、内容、， 附件，以及收件人
  • 完全附件支持 -发送和接收文件附件
  • 下载电子邮件附件 到本地文件系统
  • 支持HTML电子邮件和HTML和纯文本版本的多部分消息
  • 完全支持主题行和电子邮件内容中的国际字符
  • 通过高级MIME结构处理按ID读取电子邮件
  • 增强的附件显示 显示文件名、类型、大小和下载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

  2. 运行身份验证：

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

    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

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

云服务器身份验证

对于云服务器环境（如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控制台中，添加您的自定义域回调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"
      ]
    }
  }
}

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

可用工具

服务器提供以下可通过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": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

多部分电子邮件示例（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": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

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
}

14.创建筛选器(create_filter)

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

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

15.列出过滤器(list_filters)

检索所有Gmail过滤器。

{}

16.获取过滤器(get_filter)

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

{
  "filterId": "ANe1Bmj1234567890"
}

17.删除筛选器(delete_filter)

删除Gmail筛选器。

{
  "filterId": "ANe1Bmj1234567890"
}

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

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

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

筛选器管理功能

筛选条件

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

标准 示例 描述
from "sender@example.com" 来自特定发件人的电子邮件
to "recipient@example.com" 发送给特定收件人的电子邮件
subject "Meeting" 主题中包含特定文本的电子邮件
query "has:attachment" Gmail搜索查询语法
negatedQuery "spam" 不得出现的文本
hasAttachment true 带附件的电子邮件
size 10485760 电子邮件大小（字节）
sizeComparison "larger" 尺寸比较(larger, smaller)

筛选器操作

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

操作 示例 描述
addLabelIds ["IMPORTANT", "Label_Work"] 为匹配的电子邮件添加标签
removeLabelIds ["INBOX", "UNREAD"] 从匹配的电子邮件中删除标签
forward "backup@example.com" 将电子邮件转发到其他地址

筛选器模板

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

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: 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

高级功能

电子邮件附件支持

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

  • 发送附件：在中包含文件路径 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/
    • 检查文件权限

  2. 凭据格式无效

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

  3. 端口已在使用中

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

  4. 批量操作失败

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

  5. 附件问题

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

贡献

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

运行评估

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

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

许可证

麻省理工学院

支持

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

相关 MCP