Integrations
Allows AI assistants to interact with Gmail via IMAP, supporting email listing, searching, reading (with attachments), sending, and managing labels and folders through OAuth2 authentication.
Used for OAuth authentication to access Gmail services, requiring configuration of a Google Cloud Project with OAuth consent screen and credentials.
Gmail IMAP MCP 服务器
一个使用 IMAP 协议集成 Gmail 的模型上下文协议 (MCP) 服务器。该服务器允许 AI 助手与 Gmail 帐户交互,提供阅读、搜索和管理电子邮件的功能。
特征
- 使用 Gmail 进行 OAuth2 身份验证
- 使用高级搜索功能阅读 Gmail 帐户中的电子邮件
- 通过综合过滤(日期、标签、关键字等)搜索电子邮件
- 联系表单电子邮件的特殊处理
- 使用附加过滤选项查看未读电子邮件
- 发送带附件的电子邮件
- 管理标签(创建、删除、列出)
- 在标签之间移动电子邮件
- 下载附件
- 将电子邮件标记为已读/未读
- 支持多个 Gmail 帐户
- 通过MCP与AI助手集成
- 反引号处理以提高 Claude 兼容性
先决条件
在运行 Gmail IMAP MCP 服务器之前,请确保您具备以下条件:
- Python 3.12 或更高版本
- 已启用 Gmail API 的 Google Cloud 项目
- OAuth 2.0 客户端 ID 凭证
安装
从源安装
- 克隆存储库:Copy
- 创建并激活虚拟环境:Copy
- 安装软件包:Copy
设置 Google Cloud 项目
- 前往Google Cloud Console
- 创建新项目或选择现有项目
- 为您的项目启用 Gmail API:
- 导航至“API 和服务”>“库”
- 搜索“Gmail API”并启用它
- 创建 OAuth 2.0 凭据:
- 前往“API 和服务”>“凭证”
- 点击“创建凭证”>“OAuth 客户端 ID”
- 选择“桌面应用”作为应用程序类型
- 下载客户端配置文件
- 将下载的文件保存为 credentials 目录中的
client_secret.json
:Copy
最近的增强功能
增强的搜索功能
Gmail IMAP MCP 服务器现在具有显著改进的搜索功能:
- Gmail 样式查询语法:使用 Gmail 样式查询,例如
from:example@gmail.com is:unread has:attachment
- 特殊字符支持:查询带有特殊字符的标签(例如,
label:$$$$$
) - 日期范围过滤:使用
after_date
和before_date
参数按日期范围搜索电子邮件 - 组合过滤:混合搭配搜索条件,实现精确的电子邮件过滤
- 附加搜索参数:按已读/未读状态、附件等进行过滤。
联系表单电子邮件处理
对从联系表单发送的电子邮件进行特殊处理:
- 自动检测:识别从网站联系表单发送的电子邮件
- 真实发件人提取:从 Reply-To 标题或嵌入的 From 行中提取实际发件人
- 网站来源识别:显示联系表单来自哪个网站
- 清理消息提取:仅提取消息内容,删除表单元数据
- 改进的显示格式:以清晰、结构化的格式显示联系表单电子邮件
反引号 JSON 处理
增加了对处理 Claude 在 JSON 中使用反引号的倾向的支持:
- 自动转换:将反引号格式的 JSON(
name
)转换为正确的 JSON(“名称”) - 错误处理:提供有关 JSON 格式问题的有用错误消息
- 无缝集成:自动运行,无需特殊处理
Claude桌面指南
本节专门针对 Claude Desktop 使用 Gmail MCP 服务器提供指导。它重点介绍了有效处理电子邮件的关键工具和最佳实践。
主要工具和功能
1. 回复功能(关键)
有两种不同的回复功能可用,每种功能都有特定的用途:
- 回复消息:用于回复之前没有来回沟通过的新收到的电子邮件。
- 回复主题:用于继续已有来回交流的现有对话。
重要提示:请始终使用适当的回复功能:
- 使用
reply-to-message
对新消息进行初始回复 - 使用
reply-to-thread
继续现有对话 - 使用
send-email
会破坏电子邮件线程并创建断开的对话
2. 电子邮件内容检索
- get-email :在回复之前,请务必使用此工具检索联系表单的完整电子邮件内容,包括正文、标题和真实发件人信息。
Claude 的最佳实践
- 始终获取完整的电子邮件内容:在回复之前,请始终使用
get-email
查看完整的消息,包括真实的发件人信息。 - 使用合适的回复函数:回复现有邮件时切勿使用
send-email
,因为它会中断当前邮件的讨论。请使用合适的回复函数。 - 正确处理联系表单:对于联系表单提交,请检查来自
get-email
的电子邮件内容中的真实发件人信息。 - 将电子邮件标记为已读:处理电子邮件后始终将其标记为已读,以避免重复回复。
- 线程管理:继续现有对话时使用
reply-to-thread
来维护正确的电子邮件线程。
特殊情况
联系表单电子邮件
处理联系表单电子邮件时:
- 查找增强解析器提供的“真实发件人”信息
- 回复真正的发件人而不是表单提交地址
- 在代表企业时保持适当的专业语气
电子邮件 ID 和资源 URI
使用电子邮件 ID 时,您可能会遇到两种格式:
- 原始 ID(例如
12345
) - 资源 URI(例如
email://message/account_INBOX_12345
)
所有工具均已更新,可以正确处理这两种格式。
推荐的工作流程
- 使用
get-unread-emails
- 对于每封未读电子邮件,使用
get-email
检索完整内容 - 确定这是一个新对话还是现有话题的延续
- 使用适当的回复功能(
reply-to-message
或reply-to-thread
) - 使用
mark-as-read
请记住,Claude 的主要工作是妥善回复邮件,而不是发起新的对话。请务必使用正确的回复功能,以保持邮件的畅通!
工具参考
验证
authenticate-gmail
账户以供 MCP 使用
电子邮件检索
search-emails
:使用高级过滤功能搜索电子邮件get-unread-emails
:获取未读电子邮件,并提供附加过滤选项get-email
:获取特定电子邮件的完整详细信息
电子邮件发送
send-email
:发送带有可选附件的新电子邮件reply-to-message
:回复特定电子邮件reply-to-thread
:回复电子邮件主题(最新消息)
标签管理
list-labels
:列出所有可用的标签create-label
:创建新标签delete-label
:删除现有标签move-email
:在标签之间移动电子邮件
电子邮件组织
download-attachment
:下载电子邮件附件mark-as-read
:将电子邮件标记为已读mark-as-unread
:将电子邮件标记为未读
高级用法示例
使用日期范围和标签增强搜索
通过附加筛选获取未读电子邮件
使用复杂的 Gmail 查询进行搜索
架构和实施细节
凭证存储
Gmail IMAP MCP 服务器将 OAuth2 凭据存储在用户主目录的~/.gmail_imap_mcp_credentials/
中。这种方法有几个优点:
- 安全性:凭证存储在用户特定位置,而不是应用程序目录中
- 持久性:凭据在不同的会话和应用程序重新启动时仍然存在
- 兼容性:避免只读文件系统上的权限问题
凭证目录包含:
client_secret.json
:来自 Google Cloud Console 的 OAuth 客户端凭据- 每个经过身份验证的 Gmail 帐户的令牌文件(格式:
token_{email_address}.json
)
IMAP 实现
该服务器使用 Python 的imaplib2
库与 Gmail 进行 IMAP 操作。关键实现细节包括:
- 连接:通过端口 993 与 Gmail 的 IMAP 服务器(
imap.gmail.com
)建立安全连接 - 身份验证:使用 XOAUTH2 机制的 OAuth2 身份验证
- 电子邮件检索:使用 RFC822 格式检索电子邮件,并使用 Python 的
email
模块进行解析 - 标签管理:Gmail 标签通过 IMAP 邮箱操作进行管理
- Gmail 查询解析:Gmail 样式的查询被智能转换为 IMAP 搜索条件
电子邮件 ID 格式
系统中的电子邮件 ID 遵循以下格式:
在哪里:
{account}
:Gmail 帐户地址{mailbox}
:包含电子邮件的邮箱/标签{id}
:电子邮件的唯一 IMAP ID
这种格式允许系统唯一地标识不同帐户和邮箱中的电子邮件。
贡献
欢迎为改进 Gmail IMAP MCP 服务器做出贡献!欢迎随时提交问题或拉取请求。
用法
启动服务器
运行 Gmail IMAP MCP 服务器:
验证 Gmail 帐户
- 使用你的电子邮件地址进行
authenticate-gmail
- 在浏览器中遵循 OAuth2 身份验证流程
- 一旦通过身份验证,服务器将存储您的凭据以供将来使用
可用的工具和示例
Gmail IMAP MCP 服务器提供了一套全面的工具,用于与 Gmail 帐户交互。以下是所有可用工具的详细列表以及使用示例。
验证
1. 验证 Gmail
验证 Gmail 帐户以便与 MCP 服务器一起使用。
参数:
email
:用于验证的电子邮件地址
例子:
电子邮件检索和搜索
2. 搜索电子邮件
使用各种搜索条件在 Gmail 帐户中搜索电子邮件。
参数:
account
:要搜索的电子邮件帐户mailbox
:要搜索的邮箱(默认值:INBOX)query
:搜索查询limit
:返回的电子邮件的最大数量(默认值:10)
示例 - 搜索来自特定发件人的电子邮件:
示例 - 搜索具有特定主题的电子邮件:
示例 - 搜索正文中包含特定文本的电子邮件:
3. 获取未读电子邮件
从 Gmail 帐户获取未读电子邮件。
参数:
account
:用于接收电子邮件的电子邮件帐户mailbox
:用于接收电子邮件的邮箱(默认值:INBOX)limit
:返回的电子邮件的最大数量(默认值:10)
例子:
电子邮件撰写和发送
4. 发送电子邮件
从 Gmail 帐户发送带有可选附件和 HTML 内容的电子邮件。
参数:
account
:发送邮件的账户to
:收件人电子邮件地址,多个地址用逗号分隔subject
:电子邮件主题body
:纯文本电子邮件正文cc
:抄送收件人(可选)bcc
:密件抄送收件人(可选)html_body
:电子邮件正文的 HTML 版本(可选)attachments
:附件对象列表(可选)- 每个附件对象都需要:
path
:文件路径filename
:自定义文件名(可选)content_type
:MIME 类型(可选)
- 每个附件对象都需要:
示例 - 简单电子邮件:
示例 - 包含抄送、密送和 HTML 内容的电子邮件:
示例 - 带有附件的电子邮件:
5. 回复消息
使用可选附件和 HTML 内容回复特定的电子邮件消息。
参数:
account
:用于回复的电子邮件帐户email_id
:要回复的电子邮件 ID(格式:email://message/{account}_{mailbox}_{id}
或原始 ID)body
:纯文本回复正文mailbox
:包含电子邮件的邮箱(默认值:INBOX)html_body
:回复的 HTML 版本(可选)attachments
:附件对象列表(可选)- 每个附件对象都需要:
path
:文件路径filename
:自定义文件名(可选)content_type
:MIME 类型(可选)
- 每个附件对象都需要:
示例 - 简单回复:
示例 - 带附件回复:
6. 回复主题
使用可选附件和 HTML 内容回复电子邮件线程(使用线程中最新的消息)。
参数:
account
:用于回复的电子邮件帐户thread_id
:要回复的线程 ID(格式:email://message/{account}_{mailbox}_{id}
或原始 ID)body
:纯文本回复正文mailbox
:包含线程的邮箱(默认值:INBOX)html_body
:回复的 HTML 版本(可选)attachments
:附件对象列表(可选)- 每个附件对象都需要:
path
:文件路径filename
:自定义文件名(可选)content_type
:MIME 类型(可选)
- 每个附件对象都需要:
示例 - 简单线程回复:
标签管理
7. 创建标签
在 Gmail 帐户中创建新标签/邮箱。
参数:
account
:创建标签的电子邮件帐户label_name
:要创建的标签的名称
例子:
8. 删除标签
从 Gmail 帐户中删除标签/邮箱。
参数:
account
:要从中删除标签的电子邮件帐户label_name
:要删除的标签的名称
例子:
9. 列表标签
列出 Gmail 帐户中的所有标签/邮箱。
参数:
account
:列出标签的电子邮件帐户
例子:
电子邮件组织
10. 移动电子邮件
将电子邮件从一个标签/邮箱移动到另一个标签/邮箱。
参数:
account
:电子邮件账户email_id
:要移动的电子邮件 ID(格式:email://message/{account}_{mailbox}_{id}
)source_mailbox
:源邮箱target_mailbox
:目标邮箱
例子:
附件处理
11. 下载附件
从电子邮件中下载附件。
参数:
account
:电子邮件账户email_id
:电子邮件 ID(格式:email://message/{account}_{mailbox}_{id}
)attachment_index
:要下载的附件的索引(从 0 开始)mailbox
:包含电子邮件的邮箱(默认值:INBOX)download_dir
:保存附件的目录(默认值:“downloads”)
例子:
电子邮件状态管理
12. 标记为已读
将电子邮件标记为已读。
参数:
account
:电子邮件账户email_id
:电子邮件 ID(格式:email://message/{account}_{mailbox}_{id}
)mailbox
:包含电子邮件的邮箱(默认值:INBOX)
例子:
13. 标记为未读
将电子邮件标记为未读。
参数:
account
:电子邮件账户email_id
:电子邮件 ID(格式:email://message/{account}_{mailbox}_{id}
)mailbox
:包含电子邮件的邮箱(默认值:INBOX)
例子:
可用提示
服务器提供以下提示供AI助手使用:
1. 总结电子邮件
创建最近电子邮件的摘要。
参数:
account
:要汇总的电子邮件帐户mailbox
:要汇总的邮箱(默认值:INBOX)count
:要汇总的电子邮件数量(默认值:5)
例子:
与人工智能助手集成
Gmail IMAP MCP 服务器可以与支持模型上下文协议 (MCP) 的 AI 助手集成。以下是典型的工作流程:
- 身份验证:AI助手使用
authenticate-gmail
工具来验证用户的Gmail帐户。 - 电子邮件管理:助手可以使用服务器提供的各种工具检索、搜索和管理电子邮件。
- 电子邮件撰写:助手可以根据用户指示帮助起草和发送电子邮件。
- 电子邮件组织:助手可以通过创建标签、在标签之间移动电子邮件以及将电子邮件标记为已读/未读来帮助组织电子邮件。
- 电子邮件摘要:助手可以使用
summarize-emails
。
与人工智能助手连接
克劳德桌面
要将 Gmail IMAP MCP 服务器与 Claude Desktop 连接:
- 启动 Gmail IMAP MCP 服务器:Copy
- 打开 Claude Desktop 并导航至“设置”(齿轮图标)
- 向下滚动到“高级”部分,然后单击“编辑 MCP 配置”
- 添加 Gmail IMAP MCP 服务器配置:Copy
- 点击“保存”并重新启动Claude Desktop
- 您现在可以让 Claude 与您的 Gmail 帐户进行交互。为了获得最佳效果,请参阅上面的“Claude 桌面指南”部分,了解回复功能的正确使用方法以及电子邮件处理的最佳实践。建议尝试的任务:
- “显示我的未读邮件”
- “获取电子邮件 [ID] 的完整内容”
- “回复此电子邮件并注明[内容]”
- “继续此电子邮件线程以发送 [内容]”
- “将此电子邮件标记为已读”
- “搜索来自 [发件人] 的电子邮件”
**重要提示:**对于电子邮件回复,请始终使用正确的回复功能( reply-to-message
或reply-to-thread
)而不是send-email
,以维护正确的电子邮件线程!
Windsurf IDE
要将 Gmail IMAP MCP 服务器与 Windsurf IDE 连接:
- 启动 Gmail IMAP MCP 服务器:Copy
- 打开 Windsurf IDE 并导航至“设置”
- 找到“AI Flow”或“MCP Configuration”部分
- 添加 Gmail IMAP MCP 服务器配置:Copy
- 保存设置并根据需要重新启动 Windsurf
- 您现在可以要求 Cascade(Windsurf 的 AI 助手)使用与 Claude Desktop 相同的命令与您的 Gmail 帐户进行交互
常见用例
1. 电子邮件分类
2. 电子邮件搜索和组织
3. 电子邮件撰写
Gmail 特定注意事项
标签命名约定
Gmail 对标签名称有特定要求:
- 标签名称区分大小写
- 某些特殊字符可能不允许
- 无法创建或删除系统标签(例如收件箱、已发送、垃圾箱)
- 嵌套标签用正斜杠表示(例如“Projects/ProjectX”)
电子邮件 ID 格式
此 MCP 服务器使用的电子邮件 ID 格式为:
当使用需要电子邮件 ID 的工具(如mark-as-read
或move-email
)时,请确保使用电子邮件检索工具返回的完整资源 URI。
安全注意事项
- 服务器将 OAuth2 凭据本地存储在
~/.gmail_imap_mcp_credentials
目录中 - 切勿共享您的
client_secret.json
或令牌文件 - 该服务器仅使用安全连接连接到 Gmail 的 IMAP 服务器
- 电子邮件附件默认下载到
downloads
目录 - 在共享环境中使用服务器时要小心保护电子邮件数据
故障排除
身份验证问题
- 确保您的
client_secret.json
正确放置在~/.gmail_imap_mcp_credentials
目录中 - 检查您是否已在 Google Cloud 项目中启用 Gmail API
- 如果您的令牌已过期,请尝试重新验证
- 如果您看到“只读文件系统”错误,请确保凭据目录是可写的
连接问题
- 验证您的互联网连接
- 确保您的 Google 帐户没有任何可能阻止 IMAP 访问的安全限制
- 检查您是否需要在 Google 帐户设置中启用“安全性较低的应用访问”
电子邮件发送问题
- 验证您的 Gmail 帐户是否允许 SMTP 访问
- 检查您是否需要在 Google 帐户设置中启用“安全性较低的应用访问”
- 确保附件不太大(Gmail 的限制为 25MB)
标签管理问题
- 如果创建标签失败,请检查标签是否已经存在(区分大小写)
- 无法创建或删除系统标签
- 确保标签名称遵循 Gmail 的命名约定
电子邮件移动问题
- 如果在标签之间移动电子邮件失败,请确保源标签和目标标签都存在
- 检查电子邮件 ID 格式是否正确
- 验证您是否具有足够的权限来修改电子邮件
电子邮件ID解析问题
- 如果对电子邮件 ID 的操作失败,请确保使用完整的资源 URI
- 系统将 URI 的最后一部分解析为实际的电子邮件 ID
- 格式应为:
email://message/{account}_{mailbox}_{id}
执照
支持
对于问题和功能请求,请在 GitHub 存储库上打开问题。
命令行界面
除了 MCP 服务器之外,该软件包还提供了命令行界面 (CLI),可与 Gmail 帐户直接交互。
安装
安装软件包时会自动安装 CLI:
可用命令
1. 验证 Gmail 帐户
2. 回复特定消息
3. 回复主题
CLI 参数
CLI 支持以下用于回复消息和线程的参数:
account
:要使用的 Gmail 帐户email_id
/thread_id
:要回复的电子邮件/线程 IDbody
:回复消息正文(纯文本)--mailbox
:包含电子邮件/线程的邮箱(默认值:INBOX)--html
:回复正文的 HTML 版本--attachments
:附加到回复的一个或多个文件路径
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
使 AI 助手能够通过 IMAP 与 Gmail 帐户进行交互,允许他们列出、搜索、阅读和发送电子邮件、管理标签和文件夹以及通过模型上下文协议访问附件。
- Features
- Prerequisites
- Installation
- Setup Google Cloud Project
- Recent Enhancements
- Claude Desktop Guide
- Tools Reference
- Advanced Usage Examples
- Architecture and Implementation Details
- Contributing
- Usage
- Available Tools and Examples
- Available Prompts
- Integration with AI Assistants
- Connecting with AI Assistants
- Common Use Cases
- Gmail-Specific Considerations
- Security Considerations
- Troubleshooting
- License
- Support
- Command Line Interface