Gmail IMAP MCP服务器
使用IMAP集成Gmail的模型上下文协议（MCP）服务器。该服务器允许AI助手与Gmail帐户交互，提供阅读、搜索和管理电子邮件的功能。
特性
- 使用Gmail进行OAuth2身份验证
- 阅读来自Gmail帐户的电子邮件
- 使用高级查询选项搜索电子邮件
- 查看未读电子邮件
- 发送带有附件的电子邮件
- 管理标签（创建、删除、列出）
- 在标签之间移动电子邮件
- 下载附件
- 将电子邮件标记为已读/未读
- 支持多个Gmail帐户
- 通过MCP与AI助手集成
先决条件
在运行Gmail IMAP MCP服务器之前，请确保您具备以下条件：
- Python 3.12或更高版本
- 启用Gmail API的谷歌云项目
- OAuth 2.0客户端ID凭据
安装
从源代码安装
- 克隆存储库：
git clone https://github.com/yourusername/gmail-imap-mcp.git
cd gmail-imap-mcp- 创建并激活虚拟环境：
python -m venv .venv
# On Windows
.venv\Scripts\activate
# On Unix/MacOS
source .venv/bin/activate- 安装软件包：
pip install -e .设置谷歌云项目
- 转到 谷歌云控制台
- 创建新项目或选择现有项目
- 为您的项目启用Gmail API：
- 导航到“API和服务”>“库” - 搜索“Gmail API”并启用它
- 创建OAuth 2.0凭据：
- 转到“API和服务”>“凭据” - 点击“创建凭据”>“OAuth客户端ID” - 选择“桌面应用程序”作为应用程序类型 - 下载客户端配置文件
- 将下载的文件另存为
client_secret.json在凭据目录中：
mkdir -p ~/.gmail_imap_mcp_credentials
# Move the downloaded file to ~/.gmail_imap_mcp_credentials/client_secret.json架构和实现细节
凭据存储
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操作的库。关键实施细节包括：
- 连接：安全连接到Gmail的IMAP服务器(
imap.gmail.com)993号港口 - 认证：使用XOAUTH2机制的OAuth2身份验证
- 电子邮件检索：电子邮件使用RFC822格式检索，并使用Python解析
email模块 - 标签管理：Gmail标签通过IMAP邮箱操作进行管理
电子邮件ID格式
系统中的电子邮件ID遵循以下格式：
email://message/{account}_{mailbox}_{id}哪里：
{account}：Gmail帐户地址{mailbox}：包含电子邮件的邮箱/标签{id}：电子邮件的唯一IMAP ID
此格式允许系统在不同帐户和邮箱中唯一标识电子邮件。
用法
启动服务器
运行Gmail IMAP MCP服务器：
gmail-imap-mcp验证Gmail帐户
- 使用
authenticate-gmail带有您电子邮件地址的工具 - 在浏览器中遵循OAuth2身份验证流程
- 一旦通过身份验证，服务器将存储您的凭据以供将来使用
可用工具和示例
Gmail IMAP MCP服务器为与Gmail帐户交互提供了一套全面的工具。下面是所有可用工具的详细列表以及如何使用它们的示例。
认证
1.验证gmail
对要与MCP服务器一起使用的Gmail帐户进行身份验证。
参数：
email：要验证的电子邮件地址
例子：
{
"name": "authenticate-gmail",
"arguments": {
"email": "your.email@gmail.com"
}
}电子邮件检索和搜索
2.搜索电子邮件
使用各种搜索条件在Gmail帐户中搜索电子邮件。
参数：
account：要搜索的电子邮件帐户mailbox：要搜索的邮箱（默认：收件箱）query：搜索查询limit：要返回的最大电子邮件数（默认值：10）
示例-搜索来自特定发件人的电子邮件：
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"mailbox": "INBOX",
"query": "from:sender@example.com",
"limit": 5
}
}示例-搜索具有特定主题的电子邮件：
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"query": "subject:\"Meeting Invitation\""
}
}示例-搜索正文中包含特定文本的电子邮件：
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"query": "TEXT \"project update\""
}
}3.收到未读邮件
从Gmail帐户获取未读电子邮件。
参数：
account：用于接收电子邮件的电子邮件帐户mailbox：从中获取电子邮件的邮箱（默认：收件箱）limit：要返回的最大电子邮件数（默认值：10）
例子：
{
"name": "get-unread-emails",
"arguments": {
"account": "your.email@gmail.com",
"limit": 20
}
}电子邮件的撰写和发送
4.发送电子邮件
从Gmail帐户发送一封电子邮件，其中包含可选附件和HTML内容。
参数：
account：要发送的电子邮件帐户to：收件人电子邮件地址，逗号分隔为多个subject：电子邮件主题body：纯文本电子邮件正文cc：复写件收件人（可选）bcc：盲拷贝收件人（可选）html_body：电子邮件正文的HTML版本（可选）attachments：附件对象列表（可选）
- 每个附件对象都需要： - path：文件的路径 - filename：自定义文件名（可选） - content_type：MIME类型（可选）
示例-简单电子邮件：
{
"name": "send-email",
"arguments": {
"account": "your.email@gmail.com",
"to": "recipient@example.com",
"subject": "Hello from Gmail MCP",
"body": "This is a test email sent via the Gmail IMAP MCP server."
}
}示例-包含CC、BCC和HTML内容的电子邮件：
{
"name": "send-email",
"arguments": {
"account": "your.email@gmail.com",
"to": "recipient@example.com",
"subject": "Meeting Agenda",
"body": "Please find the agenda for our upcoming meeting.",
"cc": "manager@example.com",
"bcc": "archive@example.com",
"html_body": "
Meeting Agenda
Please find the agenda for our upcoming meeting.
"
}
}示例-带附件的电子邮件：
{
"name": "send-email",
"arguments": {
"account": "your.email@gmail.com",
"to": "recipient@example.com",
"subject": "Document Attached",
"body": "Please find the attached document.",
"attachments": [
{
"path": "/path/to/document.pdf",
"filename": "important_document.pdf",
"content_type": "application/pdf"
}
]
}
}标签管理
5.创建标签
在Gmail帐户中创建新标签/邮箱。
参数：
account：要在中创建标签的电子邮件帐户label_name：要创建的标签的名称
例子：
{
"name": "create-label",
"arguments": {
"account": "your.email@gmail.com",
"label_name": "ProjectX"
}
}6.删除标签
从Gmail帐户中删除标签/邮箱。
参数：
account：要从中删除标签的电子邮件帐户label_name：要删除的标签的名称
例子：
{
"name": "delete-label",
"arguments": {
"account": "your.email@gmail.com",
"label_name": "OldProject"
}
}7.列出标签
列出Gmail帐户中的所有标签/邮箱。
参数：
account：用于列出标签的电子邮件帐户
例子：
{
"name": "list-labels",
"arguments": {
"account": "your.email@gmail.com"
}
}电子邮件组织
8.移动电子邮件
将电子邮件从一个标签/邮箱移动到另一个。
参数：
account：电子邮件帐户email_id：要移动的电子邮件ID（格式：email://message/{account}_{mailbox}_{id})source_mailbox：源邮箱target_mailbox：目标邮箱
例子：
{
"name": "move-email",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345",
"source_mailbox": "INBOX",
"target_mailbox": "ProjectX"
}
}附件处理
9.下载附件
从电子邮件中下载附件。
参数：
account：电子邮件帐户email_id：电子邮件ID（格式：email://message/{account}_{mailbox}_{id})attachment_index：要下载的附件索引（从0开始）mailbox：包含电子邮件的邮箱（默认：收件箱）download_dir：保存附件的目录（默认：“downloads”）
例子：
{
"name": "download-attachment",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345",
"attachment_index": 0,
"download_dir": "my_attachments"
}
}电子邮件状态管理
10.标记为已读
将电子邮件标记为已读。
参数：
account：电子邮件帐户email_id：电子邮件ID（格式：email://message/{account}_{mailbox}_{id})mailbox：包含电子邮件的邮箱（默认：收件箱）
例子：
{
"name": "mark-as-read",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345"
}
}11.标记为未读
将电子邮件标记为未读。
参数：
account：电子邮件帐户email_id：电子邮件ID（格式：email://message/{account}_{mailbox}_{id})mailbox：包含电子邮件的邮箱（默认：收件箱）
例子：
{
"name": "mark-as-unread",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345"
}
}可用提示
服务器为AI助手提供以下提示：
1.总结电子邮件
创建最近电子邮件的摘要。
参数：
account：要汇总的电子邮件帐户mailbox：要汇总的邮箱（默认值：收件箱）count：要汇总的电子邮件数量（默认值：5）
例子：
{
"name": "summarize-emails",
"arguments": {
"account": "your.email@gmail.com",
"mailbox": "INBOX",
"count": 10
}
}与AI助手集成
Gmail IMAP MCP服务器可以与支持模型上下文协议（MCP）的AI助手集成。以下是一个典型的工作流程：
- 认证：AI助手使用
authenticate-gmail验证用户Gmail帐户的工具。
- 电子邮件管理：助手可以使用服务器提供的各种工具检索、搜索和管理电子邮件。
- 电子邮件撰写：助手可以根据用户指令帮助起草和发送电子邮件。
- 电子邮件组织：该助手可以通过创建标签、在标签之间移动电子邮件以及将电子邮件标记为已读/未读来帮助组织电子邮件。
- 电子邮件摘要：助理可以使用
summarize-emails提示。
与AI助手连接
克劳德桌面
要将Gmail IMAP MCP服务器与Claude Desktop连接，请执行以下操作：
- 启动Gmail IMAP MCP服务器：
python -m gmail_imap_mcp.server- 打开克劳德桌面并导航到设置（齿轮图标）
- 向下滚动到“高级”部分，然后单击“编辑MCP配置”
- 添加Gmail IMAP MCP服务器配置：
{
"servers": [
{
"name": "Gmail IMAP",
"url": "http://localhost:8080",
"tools": [
"list-emails",
"get-email",
"search-emails",
"send-email",
"list-mailboxes",
"create-label",
"move-email",
"mark-as-read",
"download-attachment"
]
}
]
}- 点击“保存”并重新启动Claude Desktop
- 您现在可以让Claude与您的Gmail帐户进行交互，例如：
- “显示我的未读电子邮件” - “向\[收件人\]发送一封关于\[主题\]的电子邮件” - “创建一个名为“重要”的新标签” - “将电子邮件从\[发件人\]移动到“重要”标签”
Windsurf IDE
要将Gmail IMAP MCP服务器与Windsurf IDE连接，请执行以下操作：
- 启动Gmail IMAP MCP服务器：
python -m gmail_imap_mcp.server- 打开Windsurf IDE并导航到设置
- 找到“AI流程”或“MCP配置”部分
- 添加Gmail IMAP MCP服务器配置：
{
"servers": [
{
"name": "Gmail IMAP",
"url": "http://localhost:8080",
"tools": [
"list-emails",
"get-email",
"search-emails",
"send-email",
"list-mailboxes",
"create-label",
"move-email",
"mark-as-read",
"download-attachment"
]
}
]
}- 保存设置，必要时重新启动Windsurf
- 现在，您可以让Cascade（Windsurf的AI助手）使用与Claude Desktop相同的命令与您的Gmail帐户进行交互
常见用例
1.电子邮件分类
Assistant: I'll help you triage your unread emails.
User: Yes, please check my unread emails.
Assistant: [Uses get-unread-emails tool]
Assistant: You have 5 unread emails. The most urgent appears to be from your boss about the quarterly report due tomorrow.
User: Mark that as read and I'll look at it right away.
Assistant: [Uses mark-as-read tool]2.电子邮件搜索和组织
Assistant: Would you like me to find specific emails for you?
User: Yes, find all emails from john@example.com about the project budget.
Assistant: [Uses search-emails tool with query "from:john@example.com project budget"]
Assistant: I found 3 emails from John about the project budget. Would you like me to create a label for these?
User: Yes, create a "Budget" label and move them there.
Assistant: [Uses create-label tool followed by move-email tool for each email]3.电子邮件撰写
Assistant: Would you like me to draft an email for you?
User: Yes, write a follow-up email to the marketing team about our campaign results.
Assistant: [Drafts email content]
Assistant: Here's a draft. Would you like me to send it?
User: Yes, but add Sarah in CC.
Assistant: [Uses send-email tool with the drafted content and CC]Gmail特定注意事项
标签命名约定
Gmail对标签名称有特定要求：
- 标签名称区分大小写
- 可能不允许使用某些特殊字符
- 无法创建或删除系统标签（如收件箱、已发送、回收站）
- 嵌套标签用正斜杠表示（例如“Projects/ProjectX”）
电子邮件ID格式
此MCP服务器使用的电子邮件ID格式为：
email://message/{account}_{mailbox}_{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目录 - 检查您是否已在谷歌云项目中启用Gmail API
- 如果您的令牌已过期，请尝试重新进行身份验证
- 如果看到“只读文件系统”错误，请确保凭据目录可写
连接问题
- 验证您的互联网连接
- 确保您的Google帐户没有任何可能阻止IMAP访问的安全限制
- 检查您是否需要在Google帐户设置中启用“不太安全的应用程序访问”
电子邮件发送问题
- 验证您的Gmail帐户是否允许SMTP访问
- 检查您是否需要在Google帐户设置中启用“不太安全的应用程序访问”
- 确保附件不要太大（Gmail有25MB的限制）
标签管理问题
- 如果创建标签失败，请检查标签是否已存在（区分大小写）
- 无法创建或删除系统标签
- 确保标签名称遵循Gmail的命名规范
电子邮件移动问题
- 如果在标签之间移动电子邮件失败，请确保源标签和目标标签都存在
- 检查电子邮件ID格式是否正确
- 验证您是否有足够的权限修改电子邮件
电子邮件ID解析问题
- 如果对电子邮件ID的操作失败，请确保您使用的是完整的资源URI
- 系统将URI的最后一部分解析为实际的电子邮件ID
- 格式应为：
email://message/{account}_{mailbox}_{id}
许可证
支持
对于问题和功能请求，请在GitHub存储库上打开问题。
