better-email-mcp

邮件

mcp-name: io.github.n24q02m/better-email-mcp

为 AI Agent 提供 IMAP/SMTP 邮件功能——跨账户读取、发送、整理邮件并管理附件。

n24q02m 的姊妹项目（点击展开）

| Project | 标语 | 标签 | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | 同一共享文件夹中的 AI Agent 彼此聊天——无需人工转发、无需编排器，工... | Tooling | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | 用于高效利用 token 进行代码审查的知识图谱——语义搜索和调用... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | 通过 .driveignore 过滤器实现双向 Google Drive 同步——rclone 引擎，Windows 托盘 | Tooling | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | 面向 AI Agent 的 IMAP/SMTP 邮件工具——读取、发送邮件，整理文件夹并管理附... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | 适用于 Godot Engine 的复合 MCP 服务——提供 17 个复合工具，助力 AI... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | 面向 AI Agent 的 Markdown 优先型 Notion——页面、数据库、区块和评论... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | 可直接替换 python-semantic-release 的分支，内置发布安全防护（孤... | Tooling | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | 面向 AI Agent 的 Telegram——支持两种机器人...上的消息、聊天、媒体和联系人 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP 服务（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...） | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | n24q02m MCP 服务的 Claude Code 插件市场——安装网页搜索... | Marketplace | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | 面向 AI Agent 的图像和视频理解与生成——支持 Gemini、Op... | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | 通过 batchexecute API 批量操作 Jules 任务的 Chrome 扩展——一... | Tooling | | [mcp-core](https://github.com/n24q02m/mcp-core) | 构建 MCP 服务的共享基础——Streamable HTTP 传输、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | 具备混合搜索和嵌入式同步功能的持久化 AI 记忆。开放、免费、无限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | 通过 ONNX Runtime 和 GGUF 实现轻量级 Qwen3 文本嵌入与重排 | Library | | [skret](https://github.com/n24q02m/skret) | 无需服务端的密钥管理。 | CLI | | [tacet](https://github.com/n24q02m/tacet) | 自蒸馏神经符号级联，通过知识...分摊大模型成本 | Tooling | | [web-core](https://github.com/n24q02m/web-core) | 用于搜索、抓取、HTTP 安全和 st...的共享 Web 基础设施包 | Library | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | 面向 AI Agent 的开源 MCP 服务：网页搜索、内容提取和库... | MCP |

目录

• 功能
• 安装
• CLI
• Smithery
• 文档
• 工具
• 比较
• 远程（HTTP 模式）
• Outlook OAuth 设备代码（HTTP 模式）
• 配置
• 安全
• 从源代码构建
• 信任模型
• 许可证

## 功能

• 多账户支持 -- 管理 6 个以上的邮箱账户（Gmail、Outlook、Yahoo、iCloud、Zoho、ProtonMail、自定义 IMAP）
• 应用专用密码 -- 大多数服务提供商无需设置 OAuth2；克隆并运行只需 1 分钟
• 4 个组合工具（另有 help）-- 通过单次调用即可搜索、读取、发送、回复、转发、整理邮件并查看凭据状态
• 自动发现 -- 根据邮箱地址检测服务提供商设置，支持自定义 IMAP 主机
• 感知邮件会话 -- 回复/转发时会保留 In-Reply-To 和 References 标头
• 分层令牌优化 -- 压缩描述 + 按需调用 help 工具 + MCP 资源

安装

该服务支持两种运行模式：stdio（默认，单用户，凭据来自环境变量）和 HTTP（选择启用，单用户，使用持有者令牌）。使用 stdio 时，将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/email@latest"],
      "env": {
        "EMAIL_CREDENTIALS": "[email protected]:app-password"
      }
    }
  }
}

该软件包为 @n24q02m/email（原名 @n24q02m/better-email-mcp；旧软件包会再发布最后一个版本，之后停止更新）。MCP Registry ID 仍为 io.github.n24q02m/better-email-mcp，旧版 better-email-mcp 命令保留为 email 的别名。

多个账户以逗号分隔：[email protected]:pass1,[email protected]:pass2。所有环境变量请参阅配置；如需运行托管的多用户服务，请参阅远程（HTTP 模式）。

大多数服务提供商使用应用专用密码（无需设置 OAuth）；Outlook/Hotmail/Live 在 HTTP 模式下使用内置的 OAuth 设备代码流程。系统会根据邮箱域名自动发现设置（IMAP/SMTP 主机、端口）。

安装矩阵

客户端	安装方式
Claude Code	/plugin marketplace add n24q02m/claude-plugins + /plugin install better-email-mcp@n24q02m-plugins（stdio；会提示输入 EMAIL_CREDENTIALS），或在 .mcp.json / 客户端设置中添加 mcpServers 条目
Codex CLI	在 ~/.codex/config.toml 中添加 [mcp_servers.email] 块（stdio 使用 command/args，HTTP 使用 type/url）
OpenCode	在 opencode.json 中添加 mcpServers 块
Cursor / Windsurf / Gemini CLI / 任何 MCP 客户端	在客户端配置中添加 mcpServers JSON，格式与上方示例相同

各客户端的完整操作指南：mcp.n24q02m.com/servers/better-email-mcp/setup/。

命令行

该软件包提供一个二进制文件 email（通过 npx @n24q02m/email 运行），也会以旧名称 better-email-mcp 安装。不带参数时，它会通过 stdio 启动 MCP 服务；此外还支持一个标志和一个子命令：

调用方式	说明
email	通过 stdio 启动 MCP 服务（默认）。从 EMAIL_CREDENTIALS，或从 EMAIL_USER + EMAIL_APP_PASSWORD 读取凭据
email --http	以 HTTP（单用户，持有者令牌）模式启动服务。等同于 MCP_TRANSPORT=http 或 TRANSPORT_MODE=http
email auth [outlook] <email> [--client-id=<id>]	通过 OAuth2 Device Code 流程验证 Outlook/Hotmail/Live 账户。令牌保存到 ~/.better-email-mcp/tokens.json。服务提供商位置参数 outlook 可省略（email 只有一个 OAuth2 服务提供商）；--client-id 可覆盖 OUTLOOK_CLIENT_ID，用于可自托管的 Azure AD 应用
email logout [<email>]	清除本地存储的 Outlook 令牌。省略 <email> 则清除所有已存储令牌

# stdio server (normally launched by your MCP client, not by hand)
EMAIL_CREDENTIALS="[email protected]:app-password" npx @n24q02m/email

# HTTP multi-user server
npx @n24q02m/email --http

# One-off Outlook OAuth device-code sign-in
npx @n24q02m/email auth [email protected]

# Sign out of a single account (or omit the email to clear all)
npx @n24q02m/email logout [email protected]

auth/logout 仅适用于 Outlook/Hotmail/Live 地址——其他服务提供商使用 EMAIL_CREDENTIALS 中的应用专用密码。HTTP 配置请参阅远程（HTTP 模式）。

Smithery

通过 Smithery 配置文件（smithery.yaml）发布。Smithery 通过 stdio 运行服务，无需构建配置；凭据来自环境变量（请参阅配置）。启动命令如下：

startCommand:
  type: stdio
  commandFunction: |-
    (config) => ({ command: 'npx', args: ['-y', '@n24q02m/email'] })

文档

完整文档请访问 mcp.n24q02m.com/servers/better-email-mcp/：

• 配置 -- Claude Code、Codex、Gemini CLI、Cursor、Windsurf、mcp.json 的安装方法

使用 AI Agent 安装 -- 将以下内容粘贴给你的 AI 编码 Agent：

按照以下步骤安装 MCP 服务 email： https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md

工具

公共工具重命名

公共工具 send 已替换为 messages，并支持 action: new、reply 或 forward。 这符合 MCP N+2 标准：发送是 messages 域中的一项操作，因此保留单独的 send 条目会重复该域，并增加冗余的工具列表和帮助主题。旧名称已直接移除；没有兼容别名。

旧公共名称	新公共名称	原因	别名移除
send	messages（action: new | reply | forward）	N+2 域工具规则：外发邮件属于 messages 超级工具，而不是第二个操作级工具。	在 Unreleased 版本中直接移除；无别名

工具	操作	描述
messages	search、read、mark_read、mark_unread、flag、unflag、move、archive、trash、new、reply、forward	搜索、读取、整理、撰写、回复和转发邮件
folders	list、status	列出邮箱文件夹，或读取指定的 IMAP STATUS 元数据
attachments	list、download	列出并下载邮件附件
config	status、setup_status、setup_start、setup_reset、setup_complete、set、cache_clear	凭据状态和配置指南、重置、重新解析、清除缓存
help	-	获取任意工具的完整文档

MCP 资源

URI	描述
email://docs/messages	邮件操作参考
email://docs/folders	文件夹操作参考
email://docs/attachments	附件操作参考
email://docs/help	完整文档
email://docs/config	凭据配置和运行时配置参考

对比

以下是 email 在各项能力上与直接竞品的对比：

能力	email	email-mcp	Gmail-MCP-Server	mcp-mail-server
IMAP/SMTP（不绑定服务提供商）	是	是	否（仅 Gmail API）	是
多账户	是（凭据以逗号分隔）	是	否（单个全局凭据）	否（每个实例对应一个账户）
应用专用密码	是（无需配置 OAuth）	是	否（仅 OAuth2）	是
根据邮箱地址自动发现	是	是（8 个服务提供商）	不适用（仅 Gmail）	否（需手动配置主机/端口）
内置 Outlook OAuth（无需用户 Azure 应用）	是（设备代码、Thunderbird 模式客户端）	部分支持（OAuth2 XOAUTH2，实验性）	否（用户提供的 Google OAuth）	否
附件（列出 + 下载）	是	是	是	是
HTTP 模式（单用户、Bearer 令牌；可自托管）	是	否（仅 stdio）	否（仅 stdio）	否（仅 stdio）

远程（HTTP 模式）

以单用户 HTTP 服务运行，并使用共享的 Bearer 令牌进行身份验证：

{
  "mcpServers": {
    "email": {
      "type": "http",
      "headers": { "Authorization": "Bearer <your-token>" },
      "url": "https://<your-host>/mcp"
    }
  }
}

自托管（HTTP 模式）

单用户模式：使用一个共享的 Bearer 令牌；账户来自环境变量或 email auth outlook <address>：

export EMAIL_MCP_TOKEN_HASH='scrypt$...'  # required: the container binds 0.0.0.0 and refuses to start without it
export EMAIL_CREDENTIALS='[email protected]:app-password'
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e EMAIL_MCP_TOKEN_HASH \
  -e EMAIL_CREDENTIALS \
  -e HOME=/data \
  -v email-data:/data \
  n24q02m/email:latest

使用 printf '%s' "$TOKEN" | email token hash 生成哈希；令牌从 stdin 读取，绝不会通过 argv 传入。客户端将原始令牌作为 Authorization: Bearer <token> 发送。已保存的 Outlook 令牌存放在 /data/.better-email-mcp/ 下，只要保留 /data 卷就会持续存在。

使用 Docker Compose 自托管

仓库提供了 docker-compose.http.yml，它会构建 http 镜像目标，并且仅在主机的回环地址上发布服务（127.0.0.1:8082）：

export EMAIL_MCP_TOKEN_HASH='scrypt$...'   # required; see the note above
export EMAIL_CREDENTIALS='[email protected]:app-password'
docker compose -f docker-compose.http.yml up

随后即可通过 http://localhost:8082 访问服务。若要向其他机器提供服务，请在同一主机上，将自己的 TLS 反向代理置于回环端口前。预构建的多架构镜像已发布到 Docker Hub（n24q02m/email） 和 GHCR（ghcr.io/n24q02m/email）。

Outlook OAuth 设备代码

Outlook/Hotmail/Live 账户使用 OAuth2 设备代码。运行一次 email auth outlook <address>。首次使用时：

1. CLI 会输出设备代码和 Microsoft 登录 URL
2. 在浏览器中打开该 URL 并输入代码
3. 登录并授权该应用
4. 令牌会保存到 ~/.better-email-mcp/tokens.json（在 POSIX 系统上创建时权限为 0600）。在 Docker 中，该路径为 /data/.better-email-mcp/tokens.json。

OAuth 使用随附的公共 Azure 客户端（d56f8c71-9f7c-43f4-9934-be29cb6e77b0，采用 Thunderbird 模式）——无需用户自行注册 Azure。

在 stdio 模式下，Outlook 账户改用应用密码（Outlook 账户设置 → 安全性 → 高级安全选项 → 应用密码）。

配置

若要自动信任 mise 配置，请在用户级配置 ~/.config/mise/config.toml 中设置 trusted_config_paths；不要将其添加到本项目的 .mise.toml 中。

变量	必填	默认值	描述
EMAIL_CREDENTIALS	是（stdio）	-	电子邮件凭据，每个账户使用 email:app-password，多个账户以逗号分隔。可选自定义 IMAP 主机/端口：email:password:imap_host:imap_port
EMAIL_USER	替代选项（stdio，单账户）	-	电子邮件地址。与 EMAIL_APP_PASSWORD 搭配使用，作为 EMAIL_CREDENTIALS 的逐字段替代方案；启动时会合并到 EMAIL_CREDENTIALS 中
EMAIL_APP_PASSWORD	替代选项（stdio，单账户）	-	应用密码（Gmail/Yahoo/iCloud）或 Outlook 应用密码；与 EMAIL_USER 搭配使用
PORT	否	0（由操作系统分配）	服务端口（http 模式）；显式设置（例如 8080）即可绑定固定端口
HOST	否	-	绑定地址（http 模式）
EMAIL_MCP_TOKEN_HASH	否（http；未绑定到回环地址时必填）	-	共享 Bearer 令牌的 scrypt 哈希值，使用 email token hash 生成。未设置时，HTTP 仅在回环地址上以未认证模式运行
OUTLOOK_CLIENT_ID	否	d56f8c71-9f7c-43f4-9934-be29cb6e77b0（随附的公共客户端）	为自托管的 Outlook OAuth2 覆盖随附的 Azure AD 公共客户端（也可在 auth 上使用 --client-id=<id>，此设置会覆盖该环境变量）
OUTLOOK_EMAIL	否	-	当 Microsoft 设备代码响应中缺少电子邮件字段时使用的解决方法
OUTLOOK_TENANT	否	consumers（stdio/CLI），common（http 设备代码）	用于登录的 Microsoft 目录；同时用于设备代码和令牌刷新端点。工作/学校（Entra ID）邮箱请设置为 common，也可以指定租户 GUID / 已验证域名来固定使用某个目录
OUTLOOK_SCOPES	否	https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send offline_access	以空格分隔的范围列表。可缩小范围（例如移除 SMTP.Send），以部署只读服务——使用较少范围授权的许可无法按完整列表刷新
OUTLOOK_EXTRA_DOMAINS	否	-	除 outlook.com/hotmail.com/live.com 之外，路由到 OAuth 的逗号分隔域名列表。自有域名上的 Microsoft 365 邮箱需要此设置，否则会被视为密码账户

多个账户

[email protected]:pass1,[email protected]:pass2,[email protected]:pass3

自定义 IMAP 主机

# Custom hostname (default port 993, implicit TLS)
[email protected]:password:imap.custom.com

# Custom hostname with a custom port
[email protected]:password:imap.custom.com:1993

# Local IMAP proxy -- "localhost" is accepted as a host, even without a dot
[email protected]:password:localhost:1993

每个账户都可以使用自己的主机和端口。非 993 端口会被视为明文/STARTTLS 连接——这是本地 IMAP 代理（例如 email-oauth2-proxy）的常见配置。

Microsoft 365 工作/学校帐户

Microsoft 365 组织中的邮箱（包括使用自有域名的邮箱）通过 Entra ID（而非消费者目录）登录。Microsoft 于 2024 年禁用了 Exchange Online 的基本身份验证，因此无法使用应用密码。要正常使用，需要设置以下两项：

# Sign in against the directory that owns the mailbox
OUTLOOK_TENANT=common                      # or a tenant GUID / verified domain

# Route your own domain to OAuth instead of asking for a password
OUTLOOK_EXTRA_DOMAINS=company.com

OUTLOOK_TENANT 同样适用于令牌刷新和初始登录——使用消费者目录刷新工作/学校帐户令牌会失败，并显示错误 AADSTS7000012: The grant was obtained for a different tenant。

如果邮箱获得的授权范围较窄（例如有 IMAP 权限，但没有 SMTP 权限），请通过 OUTLOOK_SCOPES 与之匹配，以免刷新时请求超出已授予范围的权限。

搜索查询语言

查询	说明
UNREAD	未读邮件
FLAGGED	已加星标的邮件
SINCE 2024-01-01	日期之后的邮件
FROM [email protected]	发件人为指定地址的邮件
SUBJECT meeting	主题匹配的邮件
UNREAD SINCE 2024-06-01	组合筛选条件

支持的服务提供商

服务提供商	身份验证	保存到“已发送”
Gmail	应用密码	自动（跳过）
Yahoo	应用密码	自动（跳过）
iCloud/Me.com	专用应用密码	自动（跳过）
Outlook/Hotmail/Live	OAuth2（设备代码）	IMAP APPEND
Zoho	应用密码	IMAP APPEND
ProtonMail	ProtonMail Bridge	IMAP APPEND
自定义	通过 email:pass:imap.host	IMAP APPEND

安全性

• 凭据清理 -- 错误消息中不会泄露密码
• 应用密码 -- 使用专用应用密码，而非常规密码
• 令牌存储 -- Outlook OAuth 令牌在 POSIX 系统上以 0600 模式写入（Windows 上不强制执行）
• IMAP 验证 -- 执行前会验证搜索查询

从源代码构建

git clone https://github.com/n24q02m/email.git
cd email
bun install
bun run dev

信任模型

凭据仅供单个用户使用：运行服务的用户（或使用 stdio 时的操作系统用户）均可读取凭据。存储方式取决于部署模式：

模式	存储位置	加密方式	谁可以读取你的数据？
HTTP（Docker）	环境变量（EMAIL_CREDENTIALS）和保存在 $HOME/.better-email-mcp/tokens.json 中的 Outlook 令牌（/data 卷）	令牌：明文 JSON，POSIX 文件模式 0600	服务操作者
stdio	环境变量；保存在 ~/.better-email-mcp/tokens.json 中的 Outlook 令牌；仍会读取早期版本使用的旧版 config.enc	令牌：明文 JSON，POSIX 文件模式 0600	仅你的操作系统用户

许可证

Apache-2.0 -- 详见 LICENSE。