mcp4mail

online.mcp4mailv1.0.0更新于 Sep 28, 2026

Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.

已验证Streamable HTTP可网页运行Communication & Collaboration

概览

AI 生成的概览

将 IMAP 邮箱接入为 MCP 服务器，让助手读取、搜索邮件，并在你允许时整理邮件。

功能
通过一组工具连接 IMAP 邮箱：列出已连接的账户与文件夹，按主题、发件人、收件人和日期搜索邮件，读取单封邮件，下载附件，查找往来联系人。写入类工具可以打标记、移动、移入废纸篓、保存草稿和发信。修改只对已开启相应权限的邮箱生效，send_message 也要等用户通过链接确认后才真正发出。
适用场景
适合让助手检索、分拣或总结已有邮箱，或起草回信。适合先只给读取与搜索权限、再决定是否允许修改的场景。也适合希望把 IMAP 凭据留在自己服务器上的人自行部署。
运行要求
需要经 OAuth 2.1 授权的托管远程端点，以及一个提供用户名和密码的 IMAP 账户（建议使用应用专用密码）。自行部署需要 Docker Compose、PostgreSQL，以及用于存放邮箱密码加密密钥的环境变量。
安装前请注意
托管服务会把你的 IMAP 密码保存在其服务器上（静态加密），因此更适合使用可单独撤销的应用专用密码。默认只读，但一旦打开对应邮箱的开关，助手就能打标记、移动、移入废纸篓或保存草稿，发信仍需用户点按送出。它还会在自己的数据库中保存邮件头副本，并记录每次工具调用。

安装

在 SourceWeft 中

  1. 打开 控制台中的 mcp4mail，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "mcp4mail": {
      "type": "http",
      "url": "https://mcp4mail.online/mcp"
    }
  }
}

README

mcp4mail

Your mailbox as an MCP server. Connect an IMAP account and let your AI assistant read and search your mail, authorized over OAuth 2.1. Hosted at mcp4mail.online, open source and self-hostable.

Run it yourself and your credentials never leave your machine. A hosted mail connector necessarily keeps your IMAP password on someone else's server; with mcp4mail you can keep it in your own database instead. One docker compose up gets you there: see the self-hosting guide.

Early days: the MCP endpoint lists your connected accounts; reading and searching mail is next.

This project is primarily developed by AI developers orchestrated through mcptask.online. Watch the development happen live: https://mcptask.online/live

How this project is built

This is a real open-source product and, at the same time, a public demonstration. Tasks are written by people in mcptask.online, picked up by runners (Claude Code driven by the mcptask runner, on our own machines), and every change follows the same path: task → branch → pull request → tests & CI → merge → deploy to mcp4mail.online. Nobody, person or runner, pushes to main directly: the branch is protected by a repository ruleset that requires an open pull request, a linear history, and green status checks (security scans, lint, unit tests, system tests) before a squash merge is allowed.

Watch it live: https://mcptask.online/live

Where to look if you want to verify any of this yourself: the Pull requests tab, where each PR links its task and shows its CI runs, including the failed ones; CLAUDE.md and .claude/, the instructions the runners work from; and the CI configuration.

People still write the task briefs, review the pull requests, and decide what ships and what doesn't; a runner executes a task end to end, but it is not deciding what to build. A runner is a user with a seat here, not something free or unlimited.

MCP tools

ToolWhat it does
list_mail_accountsLists the mail accounts you connected, with the ids the other tools take.
get_mail_accountShows the connection details of one account (never its password).
list_foldersLists the folders of one account.
search_messagesSearches by subject, sender, recipients and date.
get_messageReads one message.
get_attachmentDownloads an attachment of a message: a short-lived link, or with inline: true the file itself (up to 5 MB) inside the MCP answer.
search_contactsFinds addresses you have corresponded with.
get_outgoing_statusTells whether an email handed to send_message has gone out.
set_flagsFlags a message or marks it read / unread. Write.
move_messageMoves a message to another folder. Write.
trash_messageMoves a message to Trash. Write.
create_folderCreates a folder. Write.
create_draftSaves a draft. Write.
send_messagePrepares an email; it is sent only after you approve it. Write.

Write tools work only on a mailbox whose owner switched on "Allow the AI to make changes to this mailbox"; everywhere else they are refused, see below. send_message never sends on its own: you get an email with a link and the message leaves only when you press Send.

Self-hosting

bash
cp .env.example .env    # fill in the valuesdocker compose up -d

Read docs/self-hosting.md first: which environment variables matter, why HITCH_RESOURCE_URI must match your public URL exactly, TLS, and how mailbox passwords are stored.

Stack

Ruby 3.4, Rails 8.1, PostgreSQL, Hotwire (Turbo + Stimulus), Tailwind CSS, Solid Queue / Cache / Cable.

Development

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

PostgreSQL must be running locally; the default config connects over the local socket as your OS user.

Secrets

This repository is public. Nothing secret is ever committed: config/master.key, .env* and credentials.yml are git-ignored, production secrets come from the environment.

Mailbox passwords are encrypted at rest with Active Record Encryption. In production, generate keys with bin/rails db:encryption:init and provide them through the encrypted credentials (active_record_encryption.*) or the ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY and ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT environment variables. Development and test derive throwaway keys from the per-machine tmp/local_secret.txt.

Mail accounts

mcp4mail connects to your mailbox over plain IMAP with a username and password. Use an app-specific password wherever your provider offers one (Gmail, iCloud, Fastmail, Outlook.com, Yahoo and others do), so that what is stored in the database can be revoked on its own and is not the key to your whole account. How the password is stored and who can decrypt it is described in the security notes of the self-hosting guide.

MCP endpoint: read-only by design

Every mailbox is read-only until you say otherwise. Each mailbox on the Mail accounts page has one switch, "Allow the AI to make changes to this mailbox", and it is off by default. No scopes, no per-tool permissions: that switch is the whole opt-in.

  • Off (the default): the AI can only read and search. Any tool that would change the mailbox is refused with a message telling the model the mailbox is read-only, and the refusal is written to the audit log as denied.
  • On: tools that change mail (flag, move, draft and, with your approval, send) may act on that mailbox.

The tool registry refuses to boot with a tool that is neither read-only and non-destructive nor explicitly declared as a write tool (write_tool destructive: ... on McpTools::ApplicationTool), so nothing can slip in as a write tool by accident. Write tools announce readOnlyHint: false and declare their own destructiveHint.

What read-only does and does not mean, plainly:

  • Nothing can change a mailbox without its switch. Folders are opened with IMAP EXAMINE, so even reading does not mark messages as seen.

  • It does read your mail, whenever an AI client you connected asks. Connect only clients you trust with that.

  • It keeps a copy of message headers (sender, recipients, subject, date, flags, size) in its own database, refreshed every 15 minutes, so searches do not hit your mail server each time.

  • Scoping. Every tool resolves data through the signed-in user's own mail accounts; an account id that is not theirs is refused before any tool code runs.

  • Rate limits. Hitch limits each user + client pair (120 requests a minute); on top of that each user has one quota for tool calls across all their clients (240 a minute).

  • Audit log. Every call is written to mcp_audit_events: user, client, tool, account, outcome, rows returned, duration. Arguments are not stored.

  • Search guard. Pages are capped at 50 results, and each account has a budget of searches (60 per 10 minutes) and returned rows (1,000 an hour), so a runaway loop cannot walk a whole mailbox.

Contributing

See CONTRIBUTING.md. bin/ci must pass.

License

MIT

来源：README.md，提交 9bdbe93

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v1.0.0最新Sep 28, 2026