Gmail IMAP MCP Server

Name: Gmail IMAP MCP Server
Author: tonykipkemboi

本地服务

github.com/tonykipkemboi通信协作785 周前更新

代码仓库

关于 Gmail IMAP MCP Server

Gmail IMAP MCP Server 让支持 MCP 的 AI 助手通过 IMAP 管理 Gmail 邮件，适合需要在 AI 工作流中处理邮件的用户。它支持 OAuth2 和多个 Gmail 账户。

主要功能

01OAuth2 认证
02读取和搜索邮件
03发送带附件的邮件
04管理标签与邮件状态
05支持多个 Gmail 账户
06下载邮件附件

适用场景

01查找特定发件人或主题的邮件
02查看未读邮件
03发送含附件或 HTML 的邮件
04整理标签并移动邮件

MCP 相关

该 MCP 服务向 AI 助手提供 Gmail 账户认证、邮件搜索与读写、标签管理、附件处理及邮件摘要提示词。

#gmail #imap #mcp #ai-assistant #email-integration

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Gmail IMAP MCP 服务

一个使用 IMAP 集成 Gmail 的模型上下文协议（MCP）服务。此服务允许 AI 助手与 Gmail 账户交互，提供读取、搜索和管理邮件的功能。

功能

使用 Gmail 进行 OAuth2 身份验证
读取 Gmail 账户中的邮件
使用高级查询选项搜索邮件
查看未读邮件
发送带附件的邮件
管理标签（创建、删除、列出）
在标签之间移动邮件
下载附件
将邮件标记为已读或未读
支持多个 Gmail 账户
通过 MCP 与 AI 助手集成

前置条件

运行 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
# On Windows
.venv\Scripts\activate
# On Unix/MacOS
source .venv/bin/activate

安装软件包：
```
pip install -e .
```

设置 Google Cloud 项目

前往 Google Cloud Console
创建新项目或选择现有项目
为项目启用 Gmail API：
- 前往“APIs & Services” > “Library”
- 搜索“Gmail API”并启用
创建 OAuth 2.0 凭据：
- 前往“APIs & Services” > “Credentials”
- 点击“Create Credentials” > “OAuth client ID”
- 将应用类型选为“Desktop app”
- 下载客户端配置文件

将下载的文件保存为凭据目录中的 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 操作。主要实现细节包括：

连接：通过端口 993 安全连接到 Gmail 的 IMAP 服务（imap.gmail.com）
身份验证：使用 XOAUTH2 机制进行 OAuth2 身份验证
邮件获取：以 RFC822 格式获取邮件，并使用 Python 的 email 模块进行解析
标签管理：通过 IMAP 邮箱操作管理 Gmail 标签

邮件 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. authenticate-gmail

验证 Gmail 账户，以便与 MCP 服务配合使用。

参数：

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

示例：

{
  "name": "authenticate-gmail",
  "arguments": {
    "email": "[email protected]"
  }
}

邮件获取和搜索

2. search-emails

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

参数：

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

示例——搜索特定发件人的邮件：

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "mailbox": "INBOX",
    "query": "from:[email protected]",
    "limit": 5
  }
}

示例——搜索主题包含特定内容的邮件：

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "query": "subject:\"Meeting Invitation\""
  }
}

示例——搜索正文包含特定文本的邮件：

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "query": "TEXT \"project update\""
  }
}

3. get-unread-emails

获取 Gmail 账户中的未读邮件。

参数：

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

示例：

{
  "name": "get-unread-emails",
  "arguments": {
    "account": "[email protected]",
    "limit": 20
  }
}

邮件撰写与发送

4. send-email

从 Gmail 账户发送邮件，可选择添加附件和 HTML 内容。

参数：

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

示例——简单邮件：

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Hello from Gmail MCP",
    "body": "This is a test email sent via the Gmail IMAP MCP server."
  }
}

示例——包含抄送、密送和 HTML 内容的邮件：

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Meeting Agenda",
    "body": "Please find the agenda for our upcoming meeting.",
    "cc": "[email protected]",
    "bcc": "[email protected]",
    "html_body": "<h1>Meeting Agenda</h1><p>Please find the agenda for our <b>upcoming meeting</b>.</p>"
  }
}

示例——包含附件的邮件：

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Document Attached",
    "body": "Please find the attached document.",
    "attachments": [
      {
        "path": "/path/to/document.pdf",
        "filename": "important_document.pdf",
        "content_type": "application/pdf"
      }
    ]
  }
}

标签管理

5. create-label

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

参数：

account：要在其中创建标签的电子邮件账户
label_name：要创建的标签名称

示例：

{
  "name": "create-label",
  "arguments": {
    "account": "[email protected]",
    "label_name": "ProjectX"
  }
}

6. delete-label

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

参数：

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

示例：

{
  "name": "delete-label",
  "arguments": {
    "account": "[email protected]",
    "label_name": "OldProject"
  }
}

7. list-labels

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

参数：

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

示例：

{
  "name": "list-labels",
  "arguments": {
    "account": "[email protected]"
  }
}

邮件整理

8. move-email

将邮件从一个标签/邮箱移至另一个标签/邮箱。

参数：

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

示例：

{
  "name": "move-email",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345",
    "source_mailbox": "INBOX",
    "target_mailbox": "ProjectX"
  }
}

附件处理

9. download-attachment

下载邮件中的附件。

参数：

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

示例：

{
  "name": "download-attachment",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345",
    "attachment_index": 0,
    "download_dir": "my_attachments"
  }
}

邮件状态管理

10. mark-as-read

将邮件标记为已读。

参数：

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

示例：

{
  "name": "mark-as-read",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345"
  }
}

11. mark-as-unread

将邮件标记为未读。

参数：

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

示例：

{
  "name": "mark-as-unread",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345"
  }
}

可用提示词

服务提供以下提示词，供 AI 助手使用：

1. summarize-emails

汇总近期邮件。

参数：

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

示例：

{
  "name": "summarize-emails",
  "arguments": {
    "account": "[email protected]",
    "mailbox": "INBOX",
    "count": 10
  }
}

与 AI 助手集成

Gmail IMAP MCP 服务可以与支持 Model Context Protocol（MCP）的 AI 助手集成。以下是典型的工作流程：

身份验证：AI 助手使用 authenticate-gmail 工具对用户的 Gmail 账号进行身份验证。
邮件管理：助手可以使用服务提供的各种工具检索、搜索和管理邮件。
撰写邮件：助手可以根据用户的指示帮助起草并发送邮件。
整理邮件：助手可以通过创建标签、在不同标签间移动邮件，以及将邮件标记为已读或未读来帮助整理邮件。
邮件摘要：助手可以使用 summarize-emails 提示词总结邮件。

连接 AI 助手

Claude Desktop

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

启动 Gmail IMAP MCP 服务：
```
python -m gmail_imap_mcp.server
```
打开 Claude Desktop，并前往 Settings（齿轮图标）
向下滚动到“Advanced”部分，然后点击“Edit MCP Configuration”

添加 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"
      ]
    }
  ]
}

点击“Save”并重启 Claude Desktop
现在可以让 Claude 操作你的 Gmail 账号，例如：
- “显示我的未读邮件”
- “给 [recipient] 发送一封关于 [subject] 的邮件”
- “创建一个名为 ‘Important’ 的新标签”
- “将来自 [sender] 的邮件移至 ‘Important’ 标签”

Windsurf IDE

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

启动 Gmail IMAP MCP 服务：
```
python -m gmail_imap_mcp.server
```
打开 Windsurf IDE，并前往 Settings
找到“AI Flow”或“MCP Configuration”部分

添加 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 [email protected] about the project budget.
Assistant: [Uses search-emails tool with query "from:[email protected] 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 对标签名称有具体要求：

标签名称区分大小写
某些特殊字符可能不被允许
系统标签（如 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 Project 中启用 Gmail API
如果令牌已过期，请尝试重新进行身份验证
如果看到“Read-only file system”错误，请确保凭据目录可写

连接问题

检查互联网连接
确保你的 Google 账号没有可能阻止 IMAP 访问的安全限制
检查是否需要在 Google 账号设置中启用“Less secure app access”

邮件发送问题

确认你的 Gmail 账号允许 SMTP 访问
检查是否需要在 Google 账号设置中启用“Less secure app access”
确保附件没有过大（Gmail 限制为 25MB）

标签管理问题

如果创建标签失败，请检查标签是否已存在（区分大小写）
无法创建或删除系统标签
确保标签名称符合 Gmail 的命名规范

邮件移动问题

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

邮件 ID 解析问题

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

许可证

MIT 许可证

支持

如有问题或功能请求，请在 GitHub 仓库中提交 issue。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Gmail IMAP MCP Server

关于 Gmail IMAP MCP Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Gmail IMAP MCP 服务

功能

前置条件

安装

从源代码安装

设置 Google Cloud 项目

架构和实现细节

凭据存储

IMAP 实现

邮件 ID 格式

用法

启动服务

验证 Gmail 账户

可用工具和示例

身份验证

1. authenticate-gmail

邮件获取和搜索

2. search-emails

3. get-unread-emails

邮件撰写与发送

4. send-email

标签管理

5. create-label

6. delete-label

7. list-labels

邮件整理

8. move-email

附件处理

9. download-attachment

邮件状态管理

10. mark-as-read

11. mark-as-unread

可用提示词

1. summarize-emails

与 AI 助手集成

连接 AI 助手

Claude Desktop

Windsurf IDE

常见使用场景

1. 邮件筛选

2. 邮件搜索与整理

3. 撰写邮件

Gmail 特定注意事项

标签命名规范

邮件 ID 格式

安全注意事项

故障排除

身份验证问题

连接问题

邮件发送问题

标签管理问题

邮件移动问题

邮件 ID 解析问题

许可证

支持

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？