benethos-mailbox-mcp

Mailbox

一个 REST API，适用于你的所有邮箱，无论它们使用哪家服务商；同时提供 Python 客户端和基于其构建的 MCP 服务。脚本、工具和 AI Agent 都能通过一个由你掌控的入口处理邮件。

状态：测试版，版本 0.5.2。 可用于真实账户。API 或配置如有不兼容变更，会在变更日志中公布。 已存储的数据会通过迁移保留并延续使用。

目录

• 适用场景
  • 与 AI Agent 一起处理邮件
  • 更多用途
• 目前支持的功能
• 服务商
• 四个包
• 快速入门
• 文档
• 开发
• 许可证

用途

大多数人和小公司都有不止一个邮件账户：GMX 或 web.de 上的个人邮箱、Microsoft 365 上的公司邮箱、某个托管服务商提供的 info@ 地址，也可能还有 Gmail 账户。每个账户都使用自己的协议：这里是 IMAP，那里是 Microsoft Graph。所有想处理邮件的工具都必须学会这些协议，还必须拿到密码。

Mailbox 让这一切变得简单。它由四个软件包组成。mailbox-service 在你自己的机器或服务器上运行，并负责连接所有账户。其他组件只通过一个适用于所有服务提供商的统一 REST API 与该服务通信。mailbox-client 是该 API 的 Python 客户端，供脚本和应用使用。mailbox-mcp 是 MCP 服务，基于该客户端构建，可将服务开放给 AI Agent。mailbox-common 存放服务和 MCP 服务共用的内容。服务负责决定谁可以做什么。脚本、应用或 AI Agent 都会获得自己的令牌。该令牌只能访问获准的账户和操作，不能访问其他内容。

它让一些原本难以实现的事情变得简单。

使用 AI Agent 处理邮件

通过 MCP 服务，Claude 或其他 AI Agent 可以处理你授权给它的所有账户。它目前可以处理一些请求，例如：

• “昨晚以来收到了什么邮件？”
• “把 Company XY 发来的所有发票移到‘会计’文件夹。”
• “把今天的发票转发给我们的税务顾问。”
• “显示 9 月 1 日到 15 日之间 Company XY 发来的所有邮件。”
• “本周有哪些邮件带有附件？阅读发票并告诉我金额和到期日。”
• “总结有关报价的邮件，并起草一封回复。”
• “将上周的新闻简报标记为已读并移到存档。”

它的权限决定了它能否自行发送邮件，还是只能留存草稿供他人发送。授权还可以指定它能联系的收件人，例如仅限税务顾问的地址，并限制它每天可以发送的邮件数量。发送给其他人的邮件会被拒绝。还可以限制 Agent 只能访问部分文件夹，例如发票文件夹，并设置授权一周后失效。

更多用途

• 受控访问。 记账工具只能读取一个账户中的发票文件夹，不能访问其他内容。它既不能发送邮件，也不能删除邮件，而且永远看不到邮件密码，只会拿到自己的令牌。
• 跨账户自动化。 脚本可以整理发票、归档新闻简报并转发订单确认邮件。无论是 GMX、Microsoft 365，还是你自己的邮件服务器，操作方式都相同。
• 带有安全限制的邮件发送。 新闻简报任务从 info@ 地址发送邮件，只能发送给固定的收件人列表，并且每天最多发送几次。
• 用事件响应取代轮询。 签名 Webhook 会将新邮件通知你的系统，例如工单工具或内部仪表板。
• 可追溯。 所有发送操作都会记录在审计日志中，包括操作者、时间和所依据的授权。登录以及对用户、令牌、角色、账户和 Webhook 的每次变更也都会记录。
• 为自有工具提供统一收件箱。 仪表板或小型内部应用可以通过一个客户端列出、搜索并回复所有账户中的邮件。
• 可自托管。 服务会加密存储凭据。邮件直接从服务提供商发送给你，不会经过第三方云服务。

目前具备的功能

• 账户： IMAP 配合 SMTP 发送邮件，仅凭地址即可设置 （自动发现）；支持 Fastmail 和 Stalwart 等 JMAP 服务、适用于没有 IMAP 的邮箱（仅收件箱）的 POP3、通过 Microsoft Graph 和 OAuth 登录的 Microsoft 账户 （Outlook.com、Microsoft 365），以及通过 Gmail API 接入的 Gmail。 凭据使用主密钥（存放在数据库之外）进行加密（AES-256-GCM）。
• 阅读： 文件夹、邮件列表和搜索；可查看单个账户或所有账户， 跨文件夹会话、文本和 HTML 格式的邮件、附件以及原始邮件内容。消息 ID 在邮件移动后仍保持不变， 由后台同步保证。附件链接允许其他服务无需令牌即可获取文件一次。
• 撰写： 已读状态、星标和关键词、移动、删除、文件夹、草稿，以及回复、回复全部和转发。重试发送不会导致重复发送 （Idempotency-Key）。
• 变更： 变更订阅源会列出从指定时间点以来创建、更改或 删除的每封邮件，支持 IMAP、JMAP、POP3、Microsoft 和 Gmail 账户；如果 IMAP 服务器支持 CONDSTORE，也会包含在其他邮件客户端中设置的标记。Webhook 会将相同事件签名后发送到你 选择的 URL，也包括本地网络中的主机。
• 用户和权限： 用户、角色，以及按账户和操作授予的权限，细化到文件夹；可设置过期权限、API 令牌、发送限制（允许的收件人、每日发送次数）、每次发送的审计记录以及管理操作审计记录。
• MCP 服务： 通过 stdio 或可流式传输的 HTTP 读取邮件、排序、撰写草稿、发送邮件并告知最新情况；仅提供令牌允许使用的工具，并在运行期间遵循相应权限。邮件内容会标记为外部文本，再传递给模型。
• 浏览器中的配置界面，位于 /ui：账户、用户、权限、令牌、邮件读写、发送审计、Webhook、账户和同步状态、管理操作审计以及服务日志。
• 运维： 加密备份与恢复、容器映像、用于通过 Caddy 和 MCP 服务实例提供 HTTPS 的 compose 文件。

后续计划及其顺序见 docs/ROADMAP.md。

服务提供商

服务提供商	接入方式	凭据	状态
GMX、web.de、T-Online、Yahoo、AOL、iCloud、Posteo、mailbox.org、IONOS、Strato、自建邮件服务器	IMAP + SMTP	应用密码	可用
Microsoft 365、Outlook.com	Microsoft Graph	OAuth，通过项目的应用或你自己的应用（设置）	可用
Proton Mail	通过 Proton Mail Bridge 使用 IMAP + SMTP	Bridge 密码	IMAP，未经测试
Gmail / Google Workspace	Gmail API，或 IMAP + SMTP	OAuth，使用你自己的 Google Cloud 客户端（设置），或应用密码	可用
Fastmail、Stalwart 及其他 JMAP 服务	JMAP	API 令牌或密码	可用
不支持 IMAP 的旧式邮箱	POP3 + SMTP：仅收件箱，无文件夹、无已读状态、无搜索	密码	可用

不支持：Tuta 不提供 IMAP 或 API，无法接入。各服务提供商的详情见 docs/CONCEPT.md 第 5.3 节。

四个软件包

软件包	内容	运行方式	了解更多
mailbox-service	服务：REST API、配置界面、用户和权限、账户、加密凭据、提供商适配器、后台同步	持续运行	packages/mailbox-service
mailbox-client	REST API 的 Python 客户端，支持异步和同步	在你自己的代码中运行	packages/mailbox-client
mailbox-mcp	基于 mailbox-client 的 MCP 服务	每个客户端通过 stdio 运行，或作为服务通过 HTTP 运行	packages/mailbox-mcp
mailbox-common	服务和 MCP 服务共用的内容	与它们一同安装	packages/mailbox-common

每次发布都会以相同版本将全部四个软件包发布到 PyPI，名称分别为 benethos-mailbox-service、benethos-mailbox-client、 benethos-mailbox-mcp 和 benethos-mailbox-common，并将服务 和 MCP 服务作为容器 镜像发布到 ghcr.io。MCP 服务以 io.github.benethos-hub/benethos-mailbox-mcp 的名称列入官方 MCP Registry，每次发布都会将其作为 Claude Desktop 扩展一同提供， 文件名为 benethos-mailbox-mcp.mcpb。每个软件包都有自己的 README。它 会说明如何安装、启动和配置软件包；对于服务 和 MCP 服务，还会介绍如何使用容器镜像和 compose 文件。

开始使用

1. 启动服务并创建第一个用户： packages/mailbox-service。
2. 打开 http://127.0.0.1:8080/ui，使用一次性密码以 admin 身份 登录，设置自己的密码，然后连接账户。
3. 为脚本或 AI Agent 创建一个拥有所需权限的用户，并为其提供令牌 （分步说明）；如果是 Agent，还要将 MCP 服务添加到其中。Claude Desktop 会从发布版本中将其作为扩展安装，其他客户端则通过 uvx 启动：packages/mailbox-mcp。

文档

• docs/CONCEPT.md：设计、API、安全 模型
• docs/ROADMAP.md：各阶段及已完成的工作
• docs/ARCHITECTURE.md：层次、模块 以及新代码的规则
• docs/LIMITS.md：所有速率限制及其 协同方式
• docs/PERMISSIONS.md：用户、角色和权限
• docs/AUTHENTICATION.md：登录配置界面、密码和第二重验证
• docs/LOGGING.md 和 docs/AUDIT.md： 服务日志和管理操作审计
• docs/UI.md：配置界面各页面的外观 和行为
• docs/REFACTORING.md：代码布局的演变过程
• docs/IDEAS.md：收集的想法，尚未决定
• docs/MICROSOFT.md：连接 Microsoft 账户
• docs/GOOGLE.md：连接 Gmail 账户，以及你自己的 Google 客户端
• docs/openapi.json：API 合约。运行中的 服务会在 /docs 显示它
• CHANGELOG.md
• SECURITY.md：如何报告漏洞
• containers/：用于运行、开发和测试邮件服务器的 Dockerfile 和 compose 文件

开发

一个 uv 工作区、一个锁定文件、四个发行包。

uv sync
uv run pytest -q
uv run ruff check . && uv run ruff format --check .
uv run mypy

测试可离线运行。CI 也会运行这些检查，其中大多数使用组织的可复用工作流。CI 还会安装 pyproject.toml 允许的最低版本的软件包并运行测试，检查这些版本以及 uv.lock 中的每个版本是否存在 OSV 已知漏洞，并检查 assets/brand/ 中的品牌素材。所有这些检查都必须通过，更改才能合并到 main。

使用真实测试账号进行的手动检查位于 live/，相关说明见 CLAUDE.md，其中也包含本仓库的工作规则。

许可证

MIT，详见 LICENSE。