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 块中添加任何可选变量。

环境变量

对于大多数提供商（如 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

搜索和过滤电子邮件。所有参数都是可选的 — 不传递任何参数调用该工具将返回收件箱中所有电子邮件，按最新邮件优先排序。

示例：

高级用法

📚 详细文档

故障排除

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

这几乎总是意味着服务器由于 TLS/STARTTLS 不匹配而拒绝连接。请验证您的 MCP 客户端配置中以下环境变量是否设置正确：

本地 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