imap-mini-mcp

🚀 IMAP Mini MCP

IMAP Mini MCP 是一个轻量级的 MCP（模型上下文协议）服务器，用于读取 IMAP 电子邮件并创建草稿回复。它可以与任何标准的 IMAP 服务器（如 Gmail、Outlook、Fastmail 等）以及本地桥接工具（如 ProtonMail Bridge）配合使用。

代理可以读取、搜索、移动、标记星标和整理电子邮件，还能撰写草稿，但不能发送或删除电子邮件。

有关最近添加的功能，请参阅 CHANGELOG.md。

🚀 快速开始

强烈建议使用语音转文字工具（例如 Mac 上的 SuperWhisper 或 Windows 上的 Whisperflow），并将您的 AI 桌面应用程序（如 Claude、Codex 等）连接到这个 MCP 服务器。这样，您就可以通过语音与您的电子邮件收件箱进行对话，从而显著加快工作流程。

📦 安装指南

代理配置

将以下内容添加到您的 MCP 客户端配置文件（例如 claude_desktop_config.json）中：

{
  "mcpServers": {
    "imap-mini-mcp": {
      "command": "node",
      "args": ["/path/to/imap-mini-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "imap.example.com",
        "IMAP_USER": "you@example.com",
        "IMAP_PASS": "your-password"
      }
    }
  }
}

args 路径必须指向已构建的 dist/index.js。根据需要，可在 env 块中添加任何可选变量。

环境变量

| 属性 | 是否必需 | 默认值 | 详情 | |------|------|------|------| | IMAP_HOST | 是 | — | IMAP 服务器主机名（例如 imap.gmail.com） | | IMAP_USER | 是 | — | 电子邮件地址或用户名 | | IMAP_PASS | 是 | — | 密码或应用专用密码 | | IMAP_PORT | 否 | 993 | IMAP 服务器端口 | | IMAP_SECURE | 否 | true | 使用 TLS 进行连接 | | IMAP_STARTTLS | 否 | true | 通过 STARTTLS 升级到 TLS（当 IMAP_SECURE=false 时） | | IMAP_TLS_REJECT_UNAUTHORIZED | 否 | true | 拒绝自签名的 TLS 证书 |

对于大多数提供商（如 Gmail、Outlook、Fastmail），使用默认设置即可 — 只需设置主机、用户和密码。

对于 ProtonMail Bridge，以下五个设置都是必需的（该桥接工具在本地主机上监听，不使用 TLS，使用自签名证书，并且不支持 STARTTLS）：

IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SECURE=false
IMAP_STARTTLS=false
IMAP_TLS_REJECT_UNAUTHORIZED=false

或者作为 MCP 客户端配置：

{
  "mcpServers": {
    "imap-mini-mcp": {
      "command": "node",
      "args": ["/path/to/imap-mini-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "127.0.0.1",
        "IMAP_PORT": "1143",
        "IMAP_SECURE": "false",
        "IMAP_STARTTLS": "false",
        "IMAP_TLS_REJECT_UNAUTHORIZED": "false",
        "IMAP_USER": "you@proton.me",
        "IMAP_PASS": "your-bridge-password"
      }
    }
  }
}

💻 使用示例

基础用法

每个电子邮件都由一个复合 id (YYYY-MM-DDTHH:mm:ss.<Message-ID>) 标识，该 id 全局唯一，并且在文件夹移动时保持稳定。使用 find_emails 返回的 id 来获取内容、下载附件、移动电子邮件或创建回复草稿。操作工具接受一个可选的 mailbox 提示，以加快查找速度；如果省略该提示，则会搜索所有文件夹。

find_emails

搜索和过滤电子邮件。所有参数都是可选的 — 不传递任何参数调用该工具将返回收件箱中所有电子邮件，按最新邮件优先排序。 | 参数 | 类型 | 默认值 | 描述 | |------|------|------|------| | after | 字符串 | — | 仅返回此时间之后的电子邮件。可以是相对时间（如 "30m"、"2h"、"7d"）或 ISO 日期（如 "2026-02-20"） | | before | 字符串 | — | 仅返回此时间之前的电子邮件。格式与 after 相同 | | from | 字符串 | — | 发件人地址的子字符串匹配（例如 "alice@example.com"、"@stripe.com"） | | subject | 字符串 | — | 主题行的子字符串匹配 | | unread_only | 布尔值 | false | 仅返回未读电子邮件 | | has_attachment | 布尔值 | false | 仅返回带有附件的电子邮件 | | folder | 字符串 | "INBOX" | 要搜索的文件夹 | | limit | 数字 | — | 最大结果数（最新邮件优先） |

示例： | 使用场景 | 参数 | |------|------| | 过去 24 小时 | {after: "24h"} | | 过去 7 天，最多 10 封 | {after: "7d", limit: 10} | | 未读电子邮件 | {unread_only: true} | | 来自某个域名 | {from: "@stripe.com"} | | 带有附件，上个月 | {after: "30d", has_attachment: true} | | 特定发件人，在已发送文件夹中 | {from: "alice@example.com", folder: "Sent"} |

高级用法

| 工具 | 描述 | 关键参数 | |------|------|------| | list_starred_emails | 列出所有文件夹中标记星标的电子邮件 | — | | fetch_email_content | 根据 id 获取完整的电子邮件内容 | id, mailbox? | | fetch_email_attachment | 下载附件 | id, attachment_id, mailbox? | | list_folders | 列出所有文件夹 | — | | create_folder | 创建新文件夹 | path | | move_email | 将电子邮件移动到另一个文件夹 | id, destination_folder, source_folder? | | bulk_move_by_sender_email | 移动某个发件人的所有电子邮件 | sender, source_folder, destination_folder | | bulk_move_by_sender_domain | 移动某个域名的所有电子邮件 | domain, source_folder, destination_folder | | star_email | 标记电子邮件为星标 | id, mailbox? | | unstar_email | 取消电子邮件的星标标记 | id, mailbox? | | mark_read | 将电子邮件标记为已读 | id, mailbox? | | mark_unread | 将电子邮件标记为未读 | id, mailbox? | | create_draft | 创建新草稿 | to, subject, body, cc?, bcc?, in_reply_to? | | draft_reply | 根据现有电子邮件创建回复草稿 | id, body, reply_all?, mailbox? | | update_draft | 替换现有草稿（仅适用于草稿文件夹） | id, to, subject, body, cc?, bcc?, in_reply_to? |

📚 详细文档

故障排除

"IMAP 连接意外关闭" 或 "服务器断开连接"

这几乎总是意味着服务器由于 TLS/STARTTLS 不匹配而拒绝连接。请验证您的 MCP 客户端配置中以下环境变量是否设置正确： | 变量 | 检查内容 | |------|------| | IMAP_HOST | 正确的主机名或 IP | | IMAP_PORT | 与您的服务器匹配（TLS 端口为 993，普通端口为 143/1143） | | IMAP_SECURE | 端口 993 时为 true，普通连接时为 false | | IMAP_STARTTLS | 如果您的服务器不支持 STARTTLS，则为 false | | IMAP_TLS_REJECT_UNAUTHORIZED | 如果您的服务器使用自签名证书，则为 false |

本地 IMAP 桥接工具（如 ProtonMail Bridge）通常需要 IMAP_SECURE=false、IMAP_STARTTLS=false 和 IMAP_TLS_REJECT_UNAUTHORIZED=false。请参阅上面 环境变量 部分中的 ProtonMail Bridge 配置示例。

"IMAP 身份验证失败"

检查 IMAP_USER 和 IMAP_PASS 是否正确。某些提供商（如 Gmail）需要应用专用密码而不是您的账户密码。

"无法连接到 IMAP 服务器 — 连接被拒绝"

IMAP 服务器未运行或未在配置的主机和端口上监听。对于本地桥接工具，请确保桥接应用程序正在运行。

开发

构建和运行

npm install
npm run build

使用 .env 进行本地开发

要直接运行服务器（不在 MCP 客户端中），请将 .env.example 复制到 .env 并填写您的凭据，然后执行以下命令：

npm start

通过 MCP 客户端使用时，凭据将通过客户端配置的 env 块提供。

测试

测试使用 vitest 并模拟 IMAP 层 — 不需要实际的服务器连接：

npm test             # 运行一次
npm run test:watch   # 监听模式
npm run lint         # 仅进行类型检查

📄 许可证

MIT