mcp4mail

mcp4mail

将你的邮箱作为 MCP 服务。连接 IMAP 账户，让 AI 助手读取和搜索邮件，并通过 OAuth 2.1 授权。托管于 mcp4mail.online，开源且可自托管。

自行运行，凭据永远不会离开你的设备。 托管式邮件连接器必然会将你的 IMAP 密码保存在他人的服务器上；使用 mcp4mail，你可以将密码保存在自己的数据库中。只需运行一次 docker compose up 即可：请参阅自托管指南。

mcp4mail 尚处于起步阶段，我们自己也在使用它。目前，它提供了下方列出的 14 个工具：列出账户和文件夹、搜索邮件头、读取邮件、下载附件和查找联系人。它还可以更改邮箱（标记、移动、移至垃圾箱、创建文件夹、保存草稿、发送），但仅限邮箱所有者开启“允许 AI 进行更改”并勾选相应权限的情况；每个邮箱默认均为只读，且 send_message 只会准备一封邮件，只有人工按下 Send 后邮件才会发出。

试用

• 托管版： 前往 mcp4mail.online，注册、连接 IMAP 账户，然后将 https://mcp4mail.online/mcp 添加到你的 MCP 客户端。
• 自托管： 运行 cp .env.example .env，填写配置，然后运行 docker compose up -d。请参阅 自托管指南。

本项目主要由通过 mcptask.online 协调的 AI 开发者开发。实时观看开发过程：https://mcptask.online/live

本项目的构建方式

这是一个真正的开源产品，同时也是一项公开演示。任务由人们在 mcptask.online 上编写，再由执行器领取（在我们自己的机器上，由 mcptask 执行器驱动的 Claude Code），每项更改都遵循相同的流程：任务 → 分支 → 拉取请求 → 测试和 CI → 合并 → 部署到 mcp4mail.online。任何人或执行器都不会直接推送到 main：此分支受仓库规则集保护，必须先创建拉取请求、保持线性历史，并通过状态检查（安全扫描、lint、单元测试、系统测试），之后才能进行 squash 合并。

实时观看：https://mcptask.online/live

如果你想亲自核实这些内容，可以查看：拉取请求标签页，其中每个 PR 都关联了对应任务，并显示其 CI 运行情况，包括失败的运行；CLAUDE.md 和 .claude/，这是执行器遵循的说明；以及 CI 配置。

任务简述仍由人编写，拉取请求由人审查，哪些内容发布也由人决定；执行器会端到端执行任务，但不会决定要构建什么。执行器是在这里拥有席位的用户，并非免费或无限的服务。

MCP 工具

将你的 AI 客户端指向 https://mcp4mail.online/mcp（或你自己的实例的 /mcp URL）并登录。 Claude、Claude Code、ChatGPT、Cursor 和 VS Code 的操作步骤：docs/mcp-clients.md。

工具	功能
list_mail_accounts	列出你已连接的邮件帐户，以及其他工具所需的帐户 ID。
get_mail_account	显示一个帐户的连接详情（绝不会显示其密码）。
list_folders	列出一个帐户的文件夹。
search_messages	按主题、发件人、收件人、附件名称和日期搜索。
get_message	读取一封邮件。
get_attachment	下载邮件附件：获取一个短时有效的链接，或通过 inline: true 在 MCP 答复中直接获取文件（最大 5 MB）。
search_contacts	查找你曾与之通信的地址。
get_outgoing_status	告知交由 send_message 处理的邮件是否已发出。
set_flags	为邮件添加标记，或将其标记为已读／未读。写入操作。
move_message	将邮件移至另一个文件夹。写入操作。
trash_message	将邮件移至废纸篓。写入操作。
create_folder	创建文件夹。写入操作。
create_draft	保存草稿。写入操作。
send_message	准备一封邮件；只有在你批准后才会发送。写入操作。

写入工具仅适用于所有者已开启“允许 AI 修改此邮箱”并勾选了相应工具操作的邮箱；其他情况下都会被拒绝，参见 下文。send_message 绝不会自行发送邮件：你会收到一封含有链接的邮件，只有点击 Send 后邮件才会发出。

自托管

cp .env.example .env    # fill in the values
docker compose up -d

请先阅读 docs/self-hosting.md：了解哪些环境变量至关重要、为何 HITCH_RESOURCE_URI 必须与公开 URL 完全一致、TLS，以及邮箱密码的存储方式。

技术栈

Ruby 3.4、Rails 8.1、PostgreSQL、Hotwire（Turbo + Stimulus）、Tailwind CSS、Solid Queue / Cache / Cable。

开发

bin/setup   # install gems, prepare the database, start the dev server
bin/dev     # web server + Tailwind watcher
bin/ci      # rubocop, security audits, tests, system tests

PostgreSQL 必须在本地运行；默认配置通过本地套接字以你的操作系统用户身份连接。

密钥

此代码库是公开的。任何秘密都不会提交：config/master.key、.env* 和 credentials.yml 均已加入 git 忽略，生产环境的密钥来自环境变量。

邮箱密码在静态存储时使用 Active Record Encryption 加密。在生产环境中，使用 bin/rails db:encryption:init 生成密钥，并通过加密凭据（active_record_encryption.*）或 ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY、ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY 和 ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT 环境变量提供这些密钥。开发和测试环境会从每台机器各自的 tmp/local_secret.txt 派生临时密钥。

邮件帐户

mcp4mail 使用用户名和密码通过普通 IMAP 连接到你的邮箱。只要邮件服务提供商支持，请务必使用专用应用密码（Gmail、iCloud、Fastmail、Outlook.com、Yahoo 等均支持），这样数据库中存储的密码可以单独撤销，且不会成为你整个帐户的密钥。 Gmail 也以相同方式受支持：开启两步验证，然后使用应用密码登录。对于 Google Workspace 帐户，管理员可以关闭 IMAP 或应用密码，且只有管理员可以重新开启。 关于密码的存储方式以及谁可以解密密码，请参阅自托管指南中的安全说明。

MCP 端点：默认只读

除非你另行设置，否则每个邮箱都是只读的。邮件账户页面上的每个邮箱都有一个开关：“允许 AI 修改此邮箱”，默认关闭。

• 关闭（默认）：AI 只能读取和搜索。任何会更改邮箱的工具都会被拒绝，并向模型说明该邮箱为只读；拒绝操作会以 denied 记录到审计日志中。
• 开启：开关下方会展开复选框，你可以勾选 AI 在该邮箱中可以执行的操作：标记为已读和加旗标（set_flags）、移动邮件和创建文件夹（move_message、create_folder）、撰写草稿（create_draft）、发送和回复（始终需要你批准）（send_message）、删除到废纸篓（trash_message）。开启开关时，所有选项都会默认勾选。未勾选的工具会像只读邮箱中的工具一样被拒绝。list_mail_accounts 和 get_mail_account 会告知模型它可以执行哪些操作。

工具注册表拒绝启动任何既非只读且非破坏性、又未明确声明为写入工具的工具（在 McpTools::ApplicationTool 上使用 write_tool destructive: ..., permission: ... 声明，其中 permission 是上述复选框之一），因此不会有工具意外混入写入工具。写入工具会声明 readOnlyHint: false，并声明自身的 destructiveHint。

简而言之，只读模式的含义如下：

• 未开启对应开关并勾选相应复选框，任何操作都无法更改邮箱。文件夹通过 IMAP EXAMINE 打开，因此即使读取邮件，也不会将其标记为已读。

• 只要你连接的 AI 客户端发起请求，它就会读取你的邮件。请只连接你信任的客户端。

• 系统会在自己的数据库中保存一份邮件头信息副本（发件人、收件人、主题、日期、标记、大小），每 15 分钟刷新一次，因此搜索时不必每次都访问你的邮件服务器。

• 范围限定。 每个工具都会通过已登录用户自己的邮件账户解析数据；如果账户 ID 不属于该用户，请求会在运行任何工具代码之前被拒绝。

• 速率限制。 Hitch 对每个用户与客户端组合进行限流（每分钟 120 个请求）；除此之外，每个用户的所有客户端共用一个工具调用配额（每分钟 240 次）。

• 审计日志。 每次调用都会写入 mcp_audit_events：用户、客户端、工具、账户、结果、返回的行数、耗时。不会存储参数。

• 搜索保护。 每页最多返回 50 个结果；每个账户还设有搜索额度（每 10 分钟 60 次）和返回行数额度（每小时 1,000 行），以防失控的循环遍历整个邮箱。

常见问题

为什么使用 IMAP，而不是 Gmail 或 Microsoft Graph API？ 目标用户使用自己的 IMAP 主机，没有可调用的供应商 API。普通 IMAP 配合用户名和应用专用密码即可在任何地方使用，因此不需要 Gmail 或 Microsoft OAuth。请参阅 邮件账户。

我的邮件密码存储在哪里？谁能解密？ 密码存储在 PostgreSQL 中，并使用 Active Record Encryption（AES-256-GCM）加密。只有在打开 IMAP 连接时才会在内存中解密，绝不会显示、由工具返回或记录到日志中。持有加密密钥的人可以解密；如果你自行托管，那个人就是你。

AI 能自行发送或删除邮件吗？ 不能。每个邮箱在所有者启用“允许 AI 进行更改”并勾选允许的操作之前，都处于只读状态。即使启用了这些操作，send_message 也只会准备一封邮件，只有你按下“发送”后邮件才会发出；删除操作则通过 trash_message 将邮件移至“垃圾箱”。请参阅 默认采用只读设计。

它会存储我的邮件吗？ 只存储邮件头信息（发件人、收件人、主题、日期、标记、大小），每 15 分钟刷新一次，避免每次搜索都访问你的邮件服务器。AI 请求邮件正文时，才会从你的邮件服务器读取。

它支持 Outlook、Exchange 或 Gmail 吗？ 如果服务提供商支持使用应用专用密码的 IMAP，则支持：Gmail、iCloud、Fastmail、Outlook.com 和 Yahoo 都支持。Exchange 服务器是否允许 IMAP 由其管理员决定。请参阅邮件账户。

它免费吗？ 是的。它采用 MIT 许可证，可自行托管；mcp4mail.online 上的托管服务也使用同一份代码运行。

参与贡献

请参阅 CONTRIBUTING.md。bin/ci 必须通过。

许可证

MIT