fourdots

@fourdots/gmail-mcp

0 Stars 352 次浏览 fourdots 更新于 2026-08-23

交流协作工具开发者工具

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

Gmail IMAP MCP 服务器

一个使用 IMAP 协议的 Gmail 集成 Model Context Protocol (MCP) 服务器。该服务器允许 AI 助手与 Gmail 账户进行交互，提供读取、搜索和管理邮件的功能。

功能

使用 OAuth2 对 Gmail 进行身份验证
从 Gmail 账户读取邮件，并具有高级搜索功能
通过全面过滤（日期、标签、关键词等）来搜索邮件
特殊处理联系表单邮件
查看未读邮件并提供更多过滤选项
发送带有附件的邮件
管理标签（创建、删除、列出）
在标签之间移动邮件
下载附件
将邮件标记为已读/未读
支持多个 Gmail 账户
通过 MCP 与 AI 助手集成
处理反引号以提高与 Claude 的兼容性

前提条件

在运行 Gmail IMAP MCP 服务器之前，请确保您具备以下条件：

Python 3.12 或更高版本
启用了 Gmail API 的 Google Cloud 项目
OAuth 2.0 客户端 ID 凭证

安装

从源代码安装

克隆仓库：

git clone https://github.com/yourusername/gmail-imap-mcp.git
cd gmail-imap-mcp
创建并激活虚拟环境：

python -m venv .venv

在 Windows 上

.venvScriptsactivate

在 Unix/MacOS 上

source .venv/bin/activate
安装包：

pip install -e .

设置 Google Cloud 项目

前往 Google Cloud 控制台
创建新项目或选择现有项目
为您的项目启用 Gmail API：
- 导航到“API 和服务”>“库”
- 搜索“Gmail API”并启用它
创建 OAuth 2.0 凭证：
- 前往“API 和服务”>“凭证”
- 点击“创建凭证”>“OAuth 客户端 ID”
- 选择“桌面应用”作为应用程序类型
- 下载客户端配置文件
将下载的文件保存为 client_secret.json 到凭据目录中：

mkdir -p ~/.gmail_imap_mcp_credentials

将下载的文件移动到 ~/.gmail_imap_mcp_credentials/client_secret.json

Claude 桌面指南

本节专门针对使用 Gmail MCP 服务器时的 Claude Desktop 提供指导。它强调了有效处理邮件的关键工具和最佳实践。

关键工具和功能

1. 回复功能（关键）

有两种不同的回复功能，每种功能都有特定用途：- reply-to-message: 用于回复新收到的、没有之前往来通信记录的邮件。

reply-to-thread: 用于继续已有对话，其中已经存在往来通信。

重要提示：始终使用适当的回复功能：

对于新消息的初次回复，请使用 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）

所有工具都已更新，可以正确处理这两种格式。

工具参考

认证

authenticate-gmail: 为MCP使用认证Gmail账户

邮件检索

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: 将邮件标记为未读

高级使用示例

带有日期范围和标签的增强搜索

json
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"mailbox": "$$$$$",
"query": "important project",
"after_date": "2023/01/01",
"before_date": "2023/12/31",
"is_unread": true,
"limit": 20
}
}

带有额外过滤的获取未读邮件

json
{
"name": "get-unread-emails",
"arguments": {
"account": "your.email@gmail.com",
"mailbox": "$$$$$",
"additional_query": "client meeting",
"after_date": "2023/06/01",
"limit": 10
}
}### 使用复杂的Gmail查询进行搜索
json
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"query": "from:client@example.com has:attachment -in:trash",
"limit": 15
}
}

架构和实现细节

凭证存储

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模块解析。
标签管理：通过IMAP邮箱操作管理Gmail标签。
Gmail查询解析：智能地将Gmail风格的查询转换为IMAP搜索条件。

邮件ID格式

系统中的邮件ID遵循以下格式：

email://message/{account}{mailbox}{id}

其中：

{account}：Gmail账户地址。
{mailbox}：包含邮件的邮箱/标签。
{id}：邮件的唯一IMAP ID。

这种格式允许系统跨不同账户和邮箱唯一标识邮件。

贡献

欢迎贡献以改进Gmail IMAP MCP服务器！请随时提交问题或拉取请求。

使用

启动服务器

运行Gmail IMAP MCP服务器：

gmail-imap-mcp

认证Gmail账户

使用authenticate-gmail工具并提供您的电子邮件地址。
在浏览器中按照OAuth2认证流程操作。
一旦认证成功，服务器将保存您的凭证以供将来使用。

可用工具和示例

Gmail IMAP MCP服务器提供了一整套用于与Gmail账户交互的工具。以下是所有可用工具的详细列表以及如何使用它们的示例。

认证

1. authenticate-gmail

认证一个Gmail账户以便与MCP服务器一起使用。

参数：

email：要认证的电子邮件地址

示例：
json
{
"name": "authenticate-gmail",
"arguments": {
"email": "your.email@gmail.com"
}
}

邮件检索和搜索

2. search-emails

使用各种搜索条件在Gmail账户中搜索邮件。

参数：

account：要搜索的电子邮件账户
mailbox：要搜索的邮箱（默认：INBOX）
query：搜索查询
limit：返回的最大邮件数量（默认：10）

示例 - 搜索特定发件人的邮件：
json
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"mailbox": "INBOX",
"query": "from:sender@example.com",
"limit": 5
}
}

示例 - 搜索具有特定主题的邮件：
json
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"query": "subject:"Meeting Invitation""
}
}

示例 - 搜索邮件正文中有特定文本的邮件：
json
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"query": "TEXT "project update""
}
}

3. get-unread-emails

从Gmail账户获取未读邮件。

参数：

account：要获取邮件的电子邮件账户
mailbox：要获取邮件的邮箱（默认：INBOX）- limit: 返回的电子邮件的最大数量（默认值：10）

示例：
json
{
"name": "get-unread-emails",
"arguments": {
"account": "your.email@gmail.com",
"limit": 20
}
}

邮件编写与发送

4. send-email

从 Gmail 账户发送带有可选附件和 HTML 内容的邮件。

参数：

account: 发送邮件的邮箱账户
to: 收件人邮箱地址，多个收件人用逗号分隔
subject: 邮件主题
body: 纯文本邮件正文
cc: 抄送收件人（可选）
bcc: 密送收件人（可选）
html_body: 邮件正文的 HTML 版本（可选）
attachments: 附件对象列表（可选）
- 每个附件对象需要：
  - path: 文件路径
  - filename: 自定义文件名（可选）
  - content_type: MIME 类型（可选）

示例 - 简单邮件：
json
{
"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 内容的邮件：
json
{
"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 AgendaPlease find the agenda for our upcoming meeting."
}
}

示例 - 带有附件的邮件：
json
{
"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. reply-to-message

回复特定邮件消息，可选择添加附件和 HTML 内容。

参数：

account: 回复邮件的邮箱账户
email_id: 要回复的邮件 ID（格式：email://message/{account}_{mailbox}_{id} 或原始 ID）
body: 纯文本回复正文
mailbox: 包含该邮件的邮箱（默认值：INBOX）
html_body: 回复的 HTML 版本（可选）
attachments: 附件对象列表（可选）
- 每个附件对象需要：
  - path: 文件路径
  - filename: 自定义文件名（可选）
  - content_type: MIME 类型（可选）

示例 - 简单回复：
json
{
"name": "reply-to-message",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345",
"body": "Thanks for your email. I ll review your proposal and get back to you soon."
}
}

示例 - 带有附件的回复：
json
{
"name": "reply-to-message",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345",
"body": "Please find my feedback attached.",
"html_body": "Please find my feedback attached.",
"attachments": [
{
"path": "/path/to/feedback.pdf",
"filename": "project_feedback.pdf"
}
]
}
}

6. reply-to-thread

回复邮件线程（使用线程中的最新消息），可选择添加附件和 HTML 内容。

参数：

account: 回复邮件的邮箱账户
thread_id: 要回复的线程 ID（格式：email://message/{account}_{mailbox}_{id} 或原始 ID）
body: 纯文本回复正文
mailbox: 包含该线程的邮箱（默认值：INBOX）
html_body: 回复的 HTML 版本（可选）
attachments: 附件对象列表（可选）
- 每个附件对象需要：
  - path: 文件路径- filename: 自定义文件名（可选）
  - content_type: MIME 类型（可选）

示例 - 简单的线程回复：
json
{
"name": "reply-to-thread",
"arguments": {
"account": "your.email@gmail.com",
"thread_id": "email://message/your.email@gmail.com_INBOX_12345",
"body": "让我们在明天的会议中继续讨论这个问题。"
}
}

标签管理

7. create-label

在 Gmail 账户中创建一个新的标签/邮箱。

参数：

account: 创建标签的电子邮件账户
label_name: 要创建的标签名称

示例：
json
{
"name": "create-label",
"arguments": {
"account": "your.email@gmail.com",
"label_name": "ProjectX"
}
}

8. delete-label

从 Gmail 账户中删除一个标签/邮箱。

参数：

account: 删除标签的电子邮件账户
label_name: 要删除的标签名称

示例：
json
{
"name": "delete-label",
"arguments": {
"account": "your.email@gmail.com",
"label_name": "OldProject"
}
}

9. list-labels

列出 Gmail 账户中的所有标签/邮箱。

参数：

account: 列出标签的电子邮件账户

示例：
json
{
"name": "list-labels",
"arguments": {
"account": "your.email@gmail.com"
}
}

邮件组织

10. move-email

将一封邮件从一个标签/邮箱移动到另一个标签/邮箱。

参数：

account: 电子邮件账户
email_id: 要移动的邮件 ID（格式：email://message/{account}_{mailbox}_{id}）
source_mailbox: 源邮箱
target_mailbox: 目标邮箱

示例：
json
{
"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"
}
}

附件处理

11. download-attachment

从邮件中下载附件。

参数：

account: 电子邮件账户
email_id: 邮件 ID（格式：email://message/{account}_{mailbox}_{id}）
attachment_index: 要下载的附件索引（基于 0）
mailbox: 包含该邮件的邮箱（默认：INBOX）
download_dir: 保存附件的目录（默认："downloads"）

示例：
json
{
"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"
}
}

邮件状态管理

12. mark-as-read

将邮件标记为已读。

参数：

account: 电子邮件账户
email_id: 邮件 ID（格式：email://message/{account}_{mailbox}_{id}）
mailbox: 包含该邮件的邮箱（默认：INBOX）

示例：
json
{
"name": "mark-as-read",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345"
}
}

13. mark-as-unread

将邮件标记为未读。

参数：

account: 电子邮件账户
email_id: 邮件 ID（格式：email://message/{account}_{mailbox}_{id}）
mailbox: 包含该邮件的邮箱（默认：INBOX）

示例：
json
{
"name": "mark-as-unread",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345"
}
}

可用提示

服务器为 AI 助手提供了以下提示：

1. summarize-emails

创建最近邮件的摘要。

参数：

account: 要汇总的电子邮件账户
mailbox: 要汇总的邮箱（默认：INBOX）
count: 要汇总的邮件数量（默认：5）

示例：
json
{
"name": "summarize-emails",
"arguments": {
"account": "your.email@gmail.com",
"mailbox": "INBOX",
"count": 10
}
}

与 AI 助手集成

Gmail IMAP MCP 服务器可以与支持模型上下文协议 (MCP) 的 AI 助手集成。这里是一个典型的工作流程：1. 身份验证：AI助手使用authenticate-gmail工具来验证用户的Gmail帐户。

邮件管理：助手可以使用服务器提供的各种工具检索、搜索和管理邮件。
撰写邮件：根据用户指示，助手可以帮助起草并发送邮件。
邮件组织：助手可以通过创建标签、在标签间移动邮件以及将邮件标记为已读/未读来帮助组织邮件。
邮件摘要：助手可以使用summarize-emails提示来总结邮件。

与AI助手连接

Claude Desktop

要将Gmail IMAP MCP服务器与Claude Desktop连接：

启动Gmail IMAP MCP服务器：
bash
python -m gmail_imap_mcp.server
打开Claude Desktop并导航到设置（齿轮图标）
向下滚动至“高级”部分，并点击“编辑MCP配置”
添加Gmail IMAP MCP服务器配置：
json
{
"servers": [
{
"name": "Gmail IMAP",
"url": "http://localhost:8080",
"tools": [
"authenticate-gmail",
"get-unread-emails",
"get-email",
"search-emails",
"reply-to-message",
"reply-to-thread",
"send-email",
"list-labels",
"create-label",
"delete-label",
"move-email",
"mark-as-read",
"mark-as-unread",
"download-attachment"
]
}
]
}
点击“保存”并重启Claude Desktop
现在您可以要求Claude与您的Gmail帐户进行交互。为了获得最佳效果，请参阅上面的“Claude Desktop指南”部分以正确使用回复功能和处理邮件的最佳实践。

推荐尝试的任务：
- “显示我的未读邮件”
- “获取邮件[ID]的完整内容”
- “用[内容]回复这封邮件”
- “用[内容]继续这个邮件线程”
- “将此邮件标记为已读”
- “搜索来自[发件人]的邮件”

重要提示：对于邮件回复，始终使用适当的回复功能（reply-to-message或reply-to-thread）而不是send-email，以保持正确的邮件线程！

Windsurf IDE

要将Gmail IMAP MCP服务器与Windsurf IDE连接：

启动Gmail IMAP MCP服务器：
bash
python -m gmail_imap_mcp.server
打开Windsurf IDE并导航到设置
找到“AI流程”或“MCP配置”部分
添加Gmail IMAP MCP服务器配置：
json
{
"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. 邮件分类

助手：我将帮助您对未读邮件进行分类。
用户：好的，请检查我的未读邮件。
助手：[使用get-unread-emails工具]
助手：您有5封未读邮件。看起来最紧急的是来自您的老板关于明天到期的季度报告。
用户：将那封邮件标记为已读，我会立即查看。
助手：[使用mark-as-read工具]

2. 邮件搜索和组织

助手：您是否希望我为您找到特定的邮件？
用户：是的，查找所有来自john@example.com关于项目预算的邮件。
助手：[使用带有查询"from:john@example.com project budget"的search-emails工具]
助手：我找到了3封John关于项目预算的邮件。您想要为这些邮件创建一个标签吗？
用户：是的，创建一个“预算”标签并将它们移过去。
助手：[先使用create-label工具，然后对每封邮件使用move-email工具]### 3. 邮件撰写

你想让我为你起草一封邮件吗？
用户：是的，请为我写一封关于我们营销活动结果的跟进邮件。
助手：[起草邮件内容]
助手：这是草稿。你想让我发送吗？
用户：是的，但请将Sarah添加到抄送列表中。
助手：[使用带有草稿内容和抄送的发送邮件工具]

Gmail 特定注意事项

标签命名约定

Gmail 对标签名称有特定要求：

标签名称区分大小写
某些特殊字符可能不被允许
系统标签（如INBOX、Sent、Trash）不能被创建或删除
嵌套标签用正斜杠表示（例如 "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目录中
检查您是否已在Google Cloud项目中启用Gmail API
如果您的令牌已过期，请尝试重新进行身份验证
如果看到“只读文件系统”错误，请确保凭据目录可写

连接问题

验证您的互联网连接
确保您的Google帐户没有任何可能阻止IMAP访问的安全限制
检查是否需要在Google帐户设置中启用“不太安全的应用程序访问”

发送邮件问题

验证您的Gmail帐户是否允许SMTP访问
检查是否需要在Google帐户设置中启用“不太安全的应用程序访问”
确保附件不超过25MB（Gmail的限制）

标签管理问题

如果创建标签失败，请检查标签是否已存在（区分大小写）
系统标签不能被创建或删除
确保标签名称遵循Gmail的命名约定

邮件移动问题

如果在标签之间移动邮件失败，请确保源标签和目标标签都存在
检查邮件ID格式是否正确
确认您有足够的权限修改该邮件

邮件ID解析问题

如果对邮件ID的操作失败，请确保您使用的是完整的资源URI
系统会解析URI的最后一部分作为实际的邮件ID
格式应为：email://message/{account}_{mailbox}_{id}

许可证

MIT许可证

支持

对于问题和功能请求，请在GitHub仓库中打开一个issue。

命令行界面

除了MCP服务器外，此软件包还提供了一个命令行界面（CLI），用于直接与Gmail帐户交互。

安装

安装包时会自动安装CLI：

bash
pip install -e .

可用命令

1. 验证Gmail帐户

bash
gmail-imap-cli authenticate your.email@gmail.com

2. 回复特定消息

bash
gmail-imap-cli reply-to-message your.email@gmail.com 12345 "Thanks for your email." --mailbox INBOX --html "Thanks for your email." --attachments /path/to/file1.pdf /path/to/file2.docx

3. 回复某个线程

bash
gmail-imap-cli reply-to-thread your.email@gmail.com 12345 "Let s continue this discussion." --mailbox INBOX --html "Let s continue this discussion." --attachments /path/to/file.pdf

CLI参数CLI 支持以下用于回复消息和线程的参数：

account: 要使用的 Gmail 账户
email_id/thread_id: 要回复的邮件/线程 ID
body: 回复消息正文（纯文本）
--mailbox: 包含该邮件/线程的邮箱（默认：INBOX）
--html: 回复正文的 HTML 版本
--attachments: 一个或多个要附加到回复中的文件路径

查看源码项目主页

服务介绍

Gmail IMAP MCP 服务器

功能

前提条件

安装

从源代码安装

在 Windows 上

在 Unix/MacOS 上

设置 Google Cloud 项目

将下载的文件移动到 ~/.gmail_imap_mcp_credentials/client_secret.json

最近的增强功能

增强的搜索功能

联系表单邮件处理

反引号 JSON 处理

Claude 桌面指南

关键工具和功能

1. 回复功能（关键）

2. 邮件内容检索

Claude 的最佳实践

特殊情况

联系表单邮件

邮件ID和资源URI

推荐工作流程

工具参考

认证

邮件检索

发送邮件

标签管理

邮件组织

高级使用示例

带有日期范围和标签的增强搜索

带有额外过滤的获取未读邮件

架构和实现细节

凭证存储

IMAP实现

邮件ID格式

贡献

使用

启动服务器

认证Gmail账户

可用工具和示例

认证

1. authenticate-gmail

邮件检索和搜索

2. search-emails

3. get-unread-emails

邮件编写与发送

4. send-email

5. reply-to-message

6. reply-to-thread

标签管理

7. create-label

8. delete-label

9. list-labels

邮件组织

10. move-email

附件处理

11. download-attachment

邮件状态管理

12. mark-as-read

13. mark-as-unread

可用提示

1. summarize-emails

与 AI 助手集成

与AI助手连接

Claude Desktop

Windsurf IDE

常见用例

1. 邮件分类

2. 邮件搜索和组织

Gmail 特定注意事项

标签命名约定

邮件ID格式

安全注意事项

故障排除

身份验证问题

连接问题

发送邮件问题

标签管理问题

邮件移动问题

开源版与企业版