星战科技xingzhan.cloud
返回市场
Gmail imap MCP

Gmail imap MCP

作者：tonykipkemboi5 星标更新：2025-03-11
安装使用来源：spider==github.com

项目介绍

Gmail IMAP MCP 服务器

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

功能

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

预备条件

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

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

安装

从源代码安装

  1. 克隆仓库：

    git clone https://github.com/yourusername/gmail-imap-mcp.git
cd gmail-imap-mcp

  2. 创建并激活虚拟环境：

    python -m venv .venv
# 在Windows上
.venv\Scripts\activate
# 在Unix/MacOS上
source .venv/bin/activate

  3. 安装包：

    pip install -e .

设置Google Cloud项目

  1. 转到Google Cloud控制台
  2. 创建一个新项目或选择现有项目
  3. 为您的项目启用Gmail API：
    • 导航至“API和服务” > “库”
    • 搜索“Gmail API”并启用它
  4. 创建OAuth 2.0凭据：
    • 导航至“API和服务” > “凭据”
    • 单击“创建凭据” > “OAuth客户端ID”
    • 选择“桌面应用”作为应用程序类型
    • 下载客户端配置文件
  5. 将下载的文件保存为client_secret.json在凭据目录中： 
    mkdir -p ~/.gmail_imap_mcp_credentials
# 将下载的文件移动到 ~/.gmail_imap_mcp_credentials/client_secret.json

架构和实现细节

凭证存储

Gmail IMAP MCP服务器将OAuth2凭证存储在用户的主目录下的~/.gmail_imap_mcp_credentials/。这种方法具有以下优点：

  1. 安全性：凭证存储在用户特定的位置，而不是应用程序目录中
  2. 持久性：凭证在不同的会话和应用程序重启之间保持不变
  3. 兼容性：避免只读文件系统上的权限问题

凭证目录包含：

  • client_secret.json：来自Google Cloud控制台的OAuth客户端凭据
  • 每个经过身份验证的Gmail账户的令牌文件（格式：token_{email_address}.json）

IMAP实现

服务器使用Python的imaplib2库来执行与Gmail的IMAP操作。关键实现细节包括：

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

邮件ID格式

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

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

其中：

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

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

使用方法

启动服务器

运行Gmail IMAP MCP服务器：

gmail-imap-mcp

认证Gmail账户

  1. 使用authenticate-gmail工具和您的电子邮件地址
  2. 在浏览器中跟随OAuth2认证流程
  3. 认证成功后，服务器将存储您的凭据以供将来使用

可用工具和示例

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

认证

1. authenticate-gmail

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

参数：

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

示例：

{
  "name": "authenticate-gmail",
  "arguments": {
    "email": "your.email@gmail.com"
  }
}

邮件检索和搜索

2. search-emails

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

参数：

  • account：要搜索的电子邮件账户
  • mailbox：要搜索的邮箱（默认：INBOX）
  • 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. get-unread-emails

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

参数：

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

示例：

{
  "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类型（可选）

示例 - 简单邮件：

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "Hello from Gmail MCP",
    "body": "这是一封通过Gmail IMAP MCP服务器发送的测试邮件。"
  }
}

示例 - 带有CC、BCC和HTML内容的邮件：

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "会议议程",
    "body": "请查看我们即将举行的会议议程。",
    "cc": "manager@example.com",
    "bcc": "archive@example.com",
    "html_body": "<h1>会议议程</h1><p>请查看我们<b>即将举行的会议</b>的议程。</p>"
  }
}

示例 - 带有附件的邮件：

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "附带文档",
    "body": "请查看附带的文档。",
    "attachments": [
      {
        "path": "/path/to/document.pdf",
        "filename": "重要文档.pdf",
        "content_type": "application/pdf"
      }
    ]
  }
}

标签管理

5. create-label

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

参数：

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

示例：

{
  "name": "create-label",
  "arguments": {
    "account": "your.email@gmail.com",
    "label_name": "项目X"
  }
}

6. delete-label

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

参数：

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

示例：

{
  "name": "delete-label",
  "arguments": {
    "account": "your.email@gmail.com",
    "label_name": "旧项目"
  }
}

7. list-labels

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

参数：

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

示例：

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

邮件组织

8. move-email

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

参数：

  • 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": "项目X"
  }
}

附件处理

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": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "attachment_index": 0,
    "download_dir": "我的附件"
  }
}

邮件状态管理

10. mark-as-read

将邮件标记为已读。

参数：

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

示例：

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

11. mark-as-unread

将邮件标记为未读。

参数：

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

示例：

{
  "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）

示例：

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

与AI助手集成

Gmail IMAP MCP服务器可以与支持Model Context Protocol（MCP）的AI助手集成。这里是一个典型的流程：

  1. 认证：AI助手使用authenticate-gmail工具对用户的Gmail账户进行认证。
  2. 邮件管理：助手可以使用服务器提供的各种工具检索、搜索和管理邮件。
  3. 邮件撰写：助手可以根据用户指令帮助起草和发送邮件。
  4. 邮件组织：助手可以帮助组织邮件，如创建标签、在标签间移动邮件以及标记邮件为已读/未读。
  5. 邮件摘要：助手可以使用summarize-emails提示来总结邮件。

连接AI助手

Claude Desktop

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

  1. 启动Gmail IMAP MCP服务器：

    python -m gmail_imap_mcp.server

  2. 打开Claude Desktop并导航到设置（齿轮图标）

  3. 向下滚动到“高级”部分并点击“编辑MCP配置”

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

  5. 点击“保存”并重新启动Claude Desktop

  6. 您现在可以要求Claude与您的Gmail账户互动，例如：

    • “显示我未读的邮件”
    • “给[收件人]发送一封关于[主题]的邮件”
    • “创建一个新的标签叫做‘重要’”
    • “将来自[发件人]的邮件移到‘重要’标签”

Windsurf IDE

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

  1. 启动Gmail IMAP MCP服务器：

    python -m gmail_imap_mcp.server

  2. 打开Windsurf IDE并导航到设置

  3. 找到“AI流”或“MCP配置”部分

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

  5. 保存设置，如有必要，重启Windsurf

  6. 您现在可以要求Cascade（Windsurf的AI助手）使用与Claude Desktop相同的命令与您的Gmail账户互动

常见用例

1. 邮件筛选

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

2. 邮件搜索和组织

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

3. 邮件撰写

助手：您想要我为您起草一封邮件吗？
用户：是的，写一封给市场团队关于我们的活动结果的跟进邮件。
助手：[起草邮件内容]
助手：这是草稿。您想要我发送吗？
用户：是的，但添加Sarah为抄送。
助手：[使用send-email工具，带有草稿内容和抄送]

Gmail特定考虑

标签名约定

Gmail对标签名有一些具体要求：

  1. 标签名区分大小写
  2. 某些特殊字符可能不允许使用
  3. 系统标签（如INBOX、Sent、Trash）不能被创建或删除
  4. 嵌套标签用正斜杠表示（例如，“Projects/项目X”）

邮件ID格式

此MCP服务器使用的邮件ID格式为：

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

当使用需要邮件ID的工具（如`