email-mcp 是一个 MCP（Model Context Protocol）服务器，通过 IMAP 和 SMTP 为 AI 助手提供全面的邮件能力，使其能够跨多个账户读取、搜索、发送、管理、安排和分析邮件。项目定位是成为 AI 助手的全功能邮件客户端，覆盖邮件的完整生命周期：读取、撰写、管理、定时和分析，而不仅仅是基础的读取与发送。
主要能力
- 通过 MCP 协议暴露 47 个工具、7 个提示词和 6 个资源。
- 支持多账户：可同时操作多个 IMAP/SMTP 账户。
- 支持 OAuth2 XOAUTH2 认证（Gmail 和 Microsoft 365，实验性）。
- 邮件定时发送：支持未来时间投递，具备分层架构（MCP 自动检查、CLI、操作系统级守护进程）。
- 日历提取、分析、按服务商感知的标签管理。
- 实时 IMAP IDLE 监听器，配合 AI 分诊、可自定义预设和静态规则。
- 引导式设置向导，自动检测服务器设置、测试连接、保存配置并输出 MCP 客户端配置片段。
- 服务商自动检测：Gmail、Outlook、Yahoo、iCloud、Fastmail、ProtonMail、Zoho、GMX。
安全与设计
- 所有连接使用 TLS/STARTTLS 加密。
- 密码不会被记录；审计跟踪记录操作但不含凭据。
- 令牌桶限流器防止滥用（可按账户配置）。
- 附件下载上限为 5 MB，使用 base64 编码。
- 配置遵循 XDG 规范，TOML 文件位于 ~/.config/email-mcp/config.toml。
- 分层服务：业务逻辑与 MCP 接线解耦，便于测试。
使用方式
- 需要 Node.js ≥ 22；也可使用 Docker，无需 Node.js。
- 服务器使用 stdio 传输。配置需先在主机上创建（通过 npx @codefuturist/email-mcp setup 或手动），再挂载到容器中。
- 提供引导式安装器，可自动检测 Claude Desktop、VS Code、Cursor、Windsurf。
- 支持手动配置多种 MCP 客户端，包括 Claude Desktop、VS Code（扩展画廊、工作区配置、用户配置）、Cursor、Windsurf、Zed、Vibe。
- 可通过 env 字段直接传递凭据，而非使用配置文件。
- MCP 工具以 email-mcp_<tool_name> 形式暴露（例如 email-mcp_list_emails）。编辑配置后需重启 Vibe。
- Docker 运行：以只读方式挂载配置目录。
- 单账户设置可覆盖配置文件。
邮件定时发送
- MCP 自动检查：服务器启动时及运行期间每 60 秒处理队列。
- CLI：email-mcp scheduler check 用于手动或基于 cron 的处理。
- 操作系统级守护进程：email-mcp scheduler install 设置 launchd（macOS）或 crontab（Linux），每分钟运行，独立于 MCP 服务器。
- 重要：必须安装守护进程才能可靠投递。否则，定时邮件仅在 AI 客户端主动连接时触发。机器需在预定时间运行；若休眠或关机，守护进程将在下次唤醒/启动时处理逾期邮件。发送失败最多重试 3 次，之后标记为 failed。
- 定时邮件以 JSON 文件存储在 ~/.local/state/email-mcp/scheduled/，带状态锁定。每条记录跟踪尝试次数（最多 3 次）和最后错误，可用 scheduler list 检查失败。
实时监听与 AI 钩子
- IMAP IDLE 监听器使用持久 IDLE 连接（独立于工具连接）实时监控配置的邮箱。
- 新邮件到达时：静态规则按 from/to/subject 模式匹配，立即应用标签、标记或标记已读（无需 AI）；剩余邮件通过 MCP sampling 使用可自定义预设提示进行 AI 分诊；若 AI 分诊禁用，则回退到日志记录（notify 模式）。
- 静态规则使用 glob 风格模式（@github.com），以 | 作为 OR 分隔符（@github.com|*@gitlab.com）。匹配内所有条件为 AND。首个匹配规则生效。
- 可用动作：labels（字符串数组）、flag（布尔）、mark_read（布尔）、alert（布尔——强制桌面通知）。
- 基于紧急程度的多通道通知路由：所有通道默认关闭，需主动启用。
- 支持平台：macOS（通过 osascript 的 Notification Center）、Linux（notify-send）、Windows（PowerShell toast）。零 npm 依赖，使用原生操作系统命令。
- 桌面通知设置因平台而异：macOS 需为运行 MCP 服务器的终端应用授予通知权限；Linux 需要 libnotify 的 notify-send，声音提醒还需 paplay，且需要运行中的显示服务器（X11/Wayland），无头/SSH 会话不可用；Windows 使用内置 PowerShell toast 通知。
- AI 可在运行时检查、测试和配置通知：check_notification_setup、test_notification、configure_alerts（可选择性持久化到配置文件）。
- 静态规则可通过 alert = true 强制桌面通知，不受紧急程度阈值影响。
- 其他特性：连接失败时指数退避自动重连（1s → 60s）；批处理将到达邮件按可配置延迟分组以减少 AI 调用；限流每分钟最多 10 次 sampling 调用；优雅降级——若客户端不支持 sampling，回退到 notify 模式；资源订阅——推送 notifications/resources/updated 以更新未读计数。
适用场景
- 希望让 AI 助手直接管理多个邮箱账户的用户。
- 需要邮件定时发送、实时监听与 AI 分诊、桌面通知提醒的场景。
- 使用 Claude Desktop、VS Code、Cursor、Windsurf、Zed、Vibe 等 MCP 客户端的开发者。
限制
- OAuth2 支持为实验性，令牌刷新和服务商特定流程可能需要在你的环境中额外测试。
- 定时邮件的可靠投递依赖操作系统级守护进程，且机器需在预定时间运行。
- 附件下载上限 5 MB。
- Linux 桌面通知需要显示服务器，无头/SSH 会话不可用。
- 需要 Node.js ≥ 22（或使用 Docker）。
- 许可证为 LGPL-3.0-or-later。
