mail-mcp

自托管、提供商无关的邮件服务。将其指向任何邮箱的 IMAP/SMTP 凭据，即可提供以下功能：

• REST API 镜像常见的邮箱操作：列出文件夹、列出/获取/搜索邮件、发送、标记、移动、删除、配额（尽力而为）。

• Webhooks（message.received）：通过持久的 IMAP IDLE 监视器实现——当新邮件到达时，向指定的 HTTP 端点发送 POST 请求（附带每个 webhook 的 bearer 密钥），如果接收端点失败，将以指数退避策略重试（最多 6 次）。

• MCP 服务器（Streamable HTTP，POST /mcp）将相同的操作以工具的形式暴露，因此任何兼容 MCP 的代理都可以直接使用。

从一开始就支持多邮箱：在 config/accounts.json 中添加任意数量的账户。

REST API 的请求体使用 Zod 进行验证（lib/schemas.js）——无效的负载将返回 422 ERR_VALIDATION_FAILED 并附带字段级别的错误，而不会到达邮件层。Webhook 订阅持久化存储在 SQLite 中（config/webhooks.sqlite，通过 better-sqlite3），而不是使用扁平的 JSON 文件。大于 MAIL_MCP_MAX_MESSAGE_SIZE（默认 25MB）的邮件将返回 bodyTruncated: true，且不包含解析后的正文/附件，以避免将大邮件加载到内存中。

设置

npm install
cp .env.example .env   # fill in MAIL_MCP_API_TOKEN and one MAILMCP_PASS_<ID> per account

将 config/accounts.json.example 复制到 config/accounts.json（已添加到 .gitignore——此文件同样不包含密码，密码仅存在于 .env 中）：

[
  {
    "id": "example",
    "user": "user@example.com",
    "imap": { "host": "imap.example.com", "port": 993, "secure": true },
    "smtp": { "host": "smtp.example.com", "port": 465, "secure": true }
  }
]

账户 id: "example" 的密码从 MAILMCP_PASS_EXAMPLE 中读取。

node index.js

默认运行在 127.0.0.1:4900（参见 MAIL_MCP_PORT）。如果需要从宿主机外部访问，请将其置于启用了 TLS 的反向代理之后。

Related MCP server: Agent Email

systemd

示例单元文件位于 deploy/mail-mcp.service——将其复制到 /etc/systemd/system/，调整路径，它通过 EnvironmentFile 从 /root/mail-mcp/.env 加载密钥。

认证

每个 REST 和 MCP 请求都需要包含 Authorization: Bearer <MAIL_MCP_API_TOKEN>。

测试

npm test              # run once
npm run test:coverage # run with coverage report

覆盖率覆盖了纯逻辑模块（lib/schemas.js、lib/accounts.js、lib/webhooks-store.js）。lib/mailclient.js 和 lib/idle-watcher.js 与实际 IMAP/SMTP 服务器通信，通过手动端到端测试而非单元测试进行验证——它们被排除在覆盖率徽章之外，以避免误导。