Gmail 自动Auth MCP 服务器
Claude Desktop的Gmail集成模式上下文协议(MCP)服务器,拥有自动认证支持. 这个服务器可以让AI助手通过自然语言交互来管理Gmail.
特征
- 发送带有主题、内容的电子邮件, 附录,和接受者
- 完整附件支持 - 发送和接收文件附件
- 下载电子邮件附件 到本地文件系统
- 支持 HTML 电子邮件和包含 HTML 和纯文本版本的多段信件
- 完全支持主题行和电子邮件内容中的国际字符
- 使用高级 MIME 结构处理的 ID 读取电子邮件信息
- 增强附件显示 显示文件名、类型、大小和下载ID
- 搜索具有各种条件的电子邮件(主题、发送者、日期范围)
- 具有创建、更新、删除和列出标签能力的综合标签管理
- 列出所有可用的 Gmail 标签( 系统和用户定义)
- 在收件箱、 发送或自定义标签中列出电子邮件
- 将电子邮件标为已读/ 未读
- 将电子邮件移动到不同的标签/文件夹
- 删除电子邮件
- 一次性高效处理多封邮件的批量操作
- 与 Gmail API 完全整合
- 启用自动浏览器的简单 OAuth2 认证流程
- 支持桌面和网络应用程序证书
- 方便全球证书存储
安装认证( A)
通过 Smithery 安装
自动为 Claude 桌面安装 Gmail 自动认证 史密斯术数字 :
npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude
手动安装
-
创建 Google 云项目并获取证书 :
a. 创建谷歌云项目:
- 转到 谷歌云控台
- 创建新工程或选择现有工程
- 为您的工程启用 Gmail API
b. 创建 OAuth 2.0 全权证书:
- 转到"AP Is & Services" > "证书"
- 点击“ 创建证书” > “ OAuth 客户端 ID”
- 选择“ Desktop app” 或“ Web 应用程序”为应用程序类型
- 给出名字并点击"Create"
- 对于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 authb. 本地认证:
# 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/ - 打开您的默认浏览器进行 Google 认证
- 证书另存为
~/.gmail-mcp/credentials.json
说明数字 :
- 认证成功后,证书被全球存储在
~/.gmail-mcp/并可以从任意目录中使用 - 支持桌面应用程序和Web应用程序证书
- 对于Web应用程序证书,请确保添加
http://localhost:3000/oauth2callback转到您授权的重定向 URI
- 寻找
-
在 Claude 桌面中配置 :
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
嵌入支持
如果您喜欢使用 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 设置中添加一个记录以解析您的域名到您的云服务器的 IP 地址
-
谷歌云平台设置 :
- 在您的 Google Cloud 主控台中, 添加您的自定义域名调用 URL( 例如 ),
https://gmail.gongrzhe.com/oauth2callback)到授权重定向的 URI 列表
- 在您的 Google Cloud 主控台中, 添加您的自定义域名调用 URL( 例如 ),
-
运行认证 :
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback -
在应用程序中配置 :
{ "mcpServers": { "gmail": { "command": "npx", "args": [ "@gongrzhe/server-gmail-autoauth-mcp" ] } } }
这种方法可以让认证流在本地主机无法访问的环境中正常工作,例如集装箱化的应用程序或云服务器.
可用工具
该服务器提供以下工具,可以通过克洛德桌面使用:
1. 发送电子邮件send_email(中文(简体) )
立即发送新邮件 。 支持纯文本、 HTML 或多部分电子邮件 带有可选文件附件。 。 。 .
基本电子邮件 :
{
"to": ["[email protected]"],
"subject": "Meeting Tomorrow",
"body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
"cc": ["[email protected]"],
"bcc": ["[email protected]"],
"mimeType": "text/plain"
}
带有附件的电子邮件 :
{
"to": ["[email protected]"],
"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": ["[email protected]"],
"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 + Plain Text) :
{
"to": ["[email protected]"],
"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": ["[email protected]"],
"subject": "Draft Report",
"body": "Here's the draft report for your review.",
"cc": ["[email protected]"],
"attachments": ["/path/to/draft_report.docx"]
}
3. 读取电子邮件(read_email(中文(简体) )
以 ID 获取特定电子邮件的内容 . 现在显示增强附件信息。 。 。 .
{
"messageId": "182ab45cd67ef"
}
强化反应包括附件细节:
Subject: Project Files
From: [email protected]
To: [email protected]
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.四. 下载附件( E)download_attachment(中文(简体) )
新建: 下载电子邮件附件到本地文件系统.
{
"messageId": "182ab45cd67ef",
"attachmentId": "ANGjdJ9fkTs-i3GCQo5o97f_itG...",
"savePath": "/path/to/downloads",
"filename": "downloaded_document.pdf"
}
参数:
messageId: 包含附件的电子邮件的IDattachmentId: 附件ID(在增强的电子邮件显示中显示)savePath: 要保存文件的目录( 可选, 默认为当前目录)filename自定义文件名( 可选的, 如果不提供则使用原始文件名)
5. 搜索电子邮件search_emails(中文(简体) )
使用 Gmail 搜索语法搜索邮件 .
{
"query": "from:[email protected] 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. 创建标签( E)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. 获取或创建标签( C)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. 创建过滤器( R)create_filter(中文(简体) )
创建一个带有自定义标准和动作的新 Gmail 过滤器.
{
"criteria": {
"from": "[email protected]",
"hasAttachment": false
},
"action": {
"addLabelIds": ["Label_Newsletter"],
"removeLabelIds": ["INBOX"]
}
}
15. 清单过滤器list_filters(中文(简体) )
获取所有 Gmail 过滤器 .
{}
16. 获取过滤器( E)get_filter(中文(简体) )
获取特定 Gmail 过滤器的细节 .
{
"filterId": "ANe1Bmj1234567890"
}
17. 删除过滤器(delete_filter(中文(简体) )
删除 Gmail 过滤器.
{
"filterId": "ANe1Bmj1234567890"
}
18. 从模板创建过滤器( N)create_filter_from_template(中文(简体) )
使用预定义的模板为常见情景创建过滤器.
{
"template": "fromSender",
"parameters": {
"senderEmail": "[email protected]",
"labelIds": ["Label_GitHub"],
"archive": true
}
}
过滤器管理特性
筛选标准
您可以根据各种标准创建过滤器 :
| 标准 | 示例 | 说明 |
|---|---|---|
from | "[email protected]" | 特定发送者的电子邮件 |
to | "[email protected]" | 发送给特定收件人的电子邮件 |
subject | "Meeting" | 主题中有特定文本的电子邮件 |
query | "has:attachment" | Gmail 搜索查询语法 |
negatedQuery | "spam" | 不得存在的文本 |
hasAttachment | true | 带有附件的电子邮件 |
size | 10485760 | 以字节表示的电子邮件大小 |
sizeComparison | "larger" | 大小比较( E)larger, (中文(简体) ), smaller(中文(简体) ) |
过滤动作
过滤器可以执行以下动作:
| 行动 | 示例 | 说明 |
|---|---|---|
addLabelIds | ["IMPORTANT", "Label_Work"] | 将标签添加到匹配邮件中 |
removeLabelIds | ["INBOX", "UNREAD"] | 从匹配的邮件中删除标签 |
forward | "[email protected]" | 将电子邮件转发到另一个地址 |
过滤模板
服务器包括用于常见过滤方案的预建模板:
1. 从发件人模板(fromSender(中文(简体) )
过滤来自特定发送者的电子邮件,并可选择存档 .
{
"template": "fromSender",
"parameters": {
"senderEmail": "[email protected]",
"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. 内容过滤模板 (E)containingText(中文(简体) )
过滤包含特定文本和可选标记的电子邮件, 同样重要 .
{
"template": "containingText",
"parameters": {
"searchText": "invoice",
"labelIds": ["Label_Finance"],
"markImportant": true
}
}
6. 邮寄列表模板 (PDF)mailingList(中文(简体) )
过滤邮件列表并选择存档邮件 .
{
"template": "mailingList",
"parameters": {
"listIdentifier": "dev-team",
"labelIds": ["Label_DevTeam"],
"archive": true
}
}
常见过滤示例
以下是一些实用过滤示例:
自动组织通讯 :
{
"criteria": {
"from": "[email protected]"
},
"action": {
"addLabelIds": ["Label_Newsletter"],
"removeLabelIds": ["INBOX"]
}
}
处理宣传邮件 :
{
"criteria": {
"query": "unsubscribe OR promotional"
},
"action": {
"addLabelIds": ["Label_Promotions"],
"removeLabelIds": ["INBOX", "UNREAD"]
}
}
老板优先发来的邮件 :
{
"criteria": {
"from": "[email protected]"
},
"action": {
"addLabelIds": ["IMPORTANT", "Label_Boss"]
}
}
大型附件 :
{
"criteria": {
"size": 10485760,
"sizeComparison": "larger",
"hasAttachment": true
},
"action": {
"addLabelIds": ["Label_LargeFiles"]
}
}
高级搜索语法
这个 search_emails 工具支持 Gmail 强大的搜索操作员 :
| 运算符 | 示例 | 说明 |
|---|---|---|
from: | from:[email protected] | 特定发送者的电子邮件 |
to: | to:[email protected] | 发送给特定收件人的电子邮件 |
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:[email protected] after:2024/01/01 has:attachment
高级特性
电子邮件附件支持
服务器提供了全面的附件功能:
- 发送附件: 将文件路径包含在
attachments发送或起草电子邮件时的数组 - 附件 检测: 自动检测 MIME 类型和文件大小
- 下载能力: 下载本地文件系统的任何电子邮件附件
- 增强显示: 查看详细附件信息,包括文件名、类型、大小和下载ID
- 多个格式: 支持所有常见文件类型(文件、图像、档案等)
- RFC822 合规: 使用节点邮件器进行 MIME 信件格式化
支持的文件类型:所有标准文件类型,包括PDF,DOCX,XLSX,PPTX,图像(PNG,JPG,GIF),档案(ZIP,RAR)等.
电子邮件内容提取
服务器从复杂的MIME结构中智能地提取电子邮件内容:
- 在有纯文本内容时优先排序
- 如果无法提供纯文本, 则返回到 HTML 内容
- 处理带有嵌入部分的多部分 MIME 信件
- 处理附件信息(文件名、类型、大小、下载ID)
- 保存原始电子邮件信头( 从、 到、 主题、 日期)
国际字符支持
服务器在电子邮件主题和内容中完全支持非ASCII字符,包括:
- 土耳其语、汉语、日语、朝鲜语和其他非拉丁字母
- 特殊字符和符号
- 适当的编码确保在电子邮件客户端中正确显示
综合标签管理
服务器提供了一整套管理Gmail标签的工具:
- 创建标签: 创建带有自定义可见度设置的新标签
- 更新标签: 重命名标签或更改其能见度设置
- 删除标签: 删除用户创建的标签(系统标签受到保护)
- 查找或创建: 获得名称标签, 如果没有找到则自动创建
- 列出全部标签: 以详细信息查看所有系统和用户标签
- 标签可见度选项: 控制标签出现在信件和标签列表中的方式
标签可见度设置包括:
messageListVisibility:控制标签是否出现在信件列表中(show或者说hide(中文(简体) )labelListVisibility: 控制标签列表中标签的显示方式(labelShow, (中文(简体) ),labelShowIfUnread,或labelHide(中文(简体) )
这些标签管理功能可以直接通过克洛德对电子邮件进行复杂的组织,而不需要切换到Gmail接口.
批量操作
服务器包括高效的批处理能力:
- 一次处理最多50个电子邮件( 配置批量大小)
- 自动分割大型邮件集以避免 API 限制
- 每项行动的详细成功/失败报告
- 处理单个重试中的重大错误
- 适合大宗收件箱管理和组织任务
安全说明
- OAuth 证书安全地存储在本地环境中(
~/.gmail-mcp/(中文(简体) ) - 服务器使用离线访问来维护持续认证
- 永远不要共享或承诺您的证书用于版本控制
- 在您的 Google 账户设置中定期审查并取消未使用的访问
- 全权证书在全球储存,但只有当前用户才能查阅
- 附件文件在本地处理, 服务器从未永久存储
解决问题
-
未找到 OAuth 密钥
- 确保
gcp-oauth.keys.json位于您的当前目录中或~/.gmail-mcp/ - 检查文件权限
- 确保
-
无效的证书格式
- 确保您的 OAuth 密钥文件包含其中任一
web或者说installed全权证书 - 对于 Web 应用程序, 校验重定向 URI 配置正确
- 确保您的 OAuth 密钥文件包含其中任一
-
已经在使用的端口
- 如果已使用3000端口, 请在运行认证前释放它
- 您可以使用该端口找到并停止进程
-
批量操作失败
- 如果批量操作失败, 它们会自动重试单个项目
- 检查特定失败的详细错误信息
- 如果遇到速率限制, 考虑减少批量大小
-
附件问题
- 未找到文件: 确保附件文件路径正确且可访问
- 权限出错: 检查服务器是否已读取附件文件
- 大小限制: Gmail 每个电子邮件都有25MB 附件大小限制
- 下载失败: 校验您对下载目录的写入权限
捐款
欢迎捐款! 请随意提交拉力请求.
运行 evals
Evals包装入一个mcp客户端,然后运行索引.ts文件,因此在测试之间不需要重建. 您可以通过前缀 npx 命令来加载环境变量 。 完整的文档可以找到 这里。 。 。 .
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
许可证
麻省理工学院
支助
如果您遇到任何问题或有问题,请在 GitHub 寄存器上存档 .