使用说明

Gmail自动认证MCP服务器

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

特性

发送包含主题、内容、附件和收件人的电子邮件
完全支持主题行和电子邮件内容中的国际字符
通过高级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

手动安装

创建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
运行身份验证：

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

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
在Claude Desktop中配置：

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

Docker支持

如果你更喜欢使用Docker：

身份验证：

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

用途：

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

云环境设置说明

配置反向代理：
- 设置n8n容器以暴露用于身份验证的端口
- 配置反向代理以转发来自您域的流量（例如。， gmail.gongrzhe.com)到这个港口
DNS配置：
- 在DNS设置中添加A记录，将域解析为云服务器的IP地址
谷歌云平台设置：
- 在您的Google Cloud控制台中，添加您的自定义域回调URL（例如。， https://gmail.gongrzhe.com/oauth2callback)到授权重定向URI列表

运行身份验证：

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

在应用程序中配置：

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

高级功能

电子邮件内容提取

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

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

国际角色支持

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

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

全面的标签管理

服务器提供了一套完整的工具来管理Gmail标签：

创建标签：使用可自定义的可见性设置创建新标签
更新标签：重命名标签或更改其可见性设置
删除标签：删除用户创建的标签（系统标签受保护）
查找或创建：按名称获取标签，如果找不到，则自动创建标签
列出所有标签：查看所有包含详细信息的系统和用户标签
标签可见性选项：控制标签在邮件和标签列表中的显示方式

标签可见性设置包括：

messageListVisibility：控制标签是否显示在消息列表中(show 或 hide)
labelListVisibility：控制标签在标签列表中的显示方式(labelShow, labelShowIfUnread，或 labelHide)

这些标签管理功能可以直接通过Claude对电子邮件进行复杂的组织，而无需切换到Gmail界面。

批量操作

该服务器包括高效的批处理功能：

一次最多处理50封电子邮件（可配置批量大小）
自动分块大型电子邮件集以避免API限制
每个操作的详细成功/失败报告
通过单独重试进行优雅的错误处理
非常适合批量收件箱管理和组织任务

安全说明

OAuth凭据安全地存储在您的本地环境中(~/.gmail-mcp/)
服务器使用脱机访问来维护持久身份验证
切勿将您的凭据共享或提交给版本控制
定期查看并撤销您Google帐户设置中未使用的访问权限
凭据是全局存储的，但只能由当前用户访问

故障排除

找不到OAuth密钥
- 确保 gcp-oauth.keys.json 位于您当前的目录或 ~/.gmail-mcp/
- 检查文件权限
凭据格式无效
- 确保您的OAuth密钥文件包含以下内容之一 web 或 installed 凭证
- 对于web应用程序，请验证重定向URI是否配置正确
端口已在使用中
- 如果端口3000已在使用中，请在运行身份验证之前将其释放
- 您可以使用该端口查找并停止进程
批量操作失败
- 如果批处理操作失败，它们会自动重试单个项目
- 检查特定故障的详细错误消息
- 如果遇到速率限制，请考虑减少批量大小

贡献

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

许可证

麻省理工学院

支持

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

使用说明

Gmail自动认证MCP服务器

特性

安装和身份验证

通过Smithery安装

手动安装

Docker支持

云服务器身份验证

云环境设置说明

可用工具

1.发送电子邮件(send_email)

2.电子邮件草稿(draft_email)

3.阅读电子邮件(read_email)

4.搜索电子邮件(search_emails)

5.修改电子邮件(modify_email)

6.删除电子邮件(delete_email)

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

8.创建标签(create_label)

9.更新标签(update_label)

10.删除标签(delete_label)

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

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

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