rubit-mcp-mail

rubit-mcp-mail

一款用于读取邮件的只读 MCP 服务。与邮件服务提供商无关：它使用 IMAP，因此可与 Outlook.com、Gmail、Fastmail、iCloud 或可自托管的服务搭配使用——提供商只需在配置中设置，无须修改代码。

从设计上确保只读。 文件夹使用 EXAMINE 打开，而非 SELECT；邮件正文使用 BODY.PEEK 获取，因此读取邮件甚至不会将其标记为已读。代码中没有发送、移动、删除或标记邮件的路径，并且有测试确保不会添加这些功能。

📖 完整文档：https://bgalmes.github.io/rubit-mcp-mail/

快速安装

从最新版本下载适用于你系统的安装程序并运行：

系统	文件
Windows	rubit-mcp-mail-setup-windows.exe
Linux	rubit-mcp-mail-setup-linux — 请先对其运行 chmod +x

无需预先安装任何内容：Python 和所有依赖项都包含在这一个文件中。窗口会询问你的服务提供商和电子邮件地址，随后为你登录；如果检测到 Claude Desktop 和 Claude Code，还会将邮件服务注册到它们中。之后重启 Claude Desktop，就能看到邮件。安装程序还会为你创建一个 rubit-mcp-mail Settings 快捷方式，方便日后更改所需设置。全程无需使用终端。

没有 macOS 安装程序；Mac 用户请从源代码安装（见下文）。

关于防病毒软件警告。 Windows Defender 或 Avast 可能会将此 .exe 标记为风险。这是未签名的 PyInstaller 构建应用程序常见的已知误报，并非本项目代码导致的问题——如何处理请参阅安装指南。所有已发布的 SHA-256 值均列在变更日志中。

工具

工具	功能
list_accounts	已配置的账户，以及每个账户是否已通过身份验证
list_folders	文件夹及其规范化角色和未读邮件数量
list_messages	浏览文件夹中的邮件，按最新优先排列并分页
search_messages	在服务端按文本、发件人、主题、日期范围和未读状态搜索
read_message	完整邮件头、正文文本和附件元数据
get_attachment	将一个附件保存到下载目录

文件夹通过角色寻址——inbox、sent、drafts、junk、trash、archive——因此你无需知道 Outlook 将其称为 Junk Email，而 Gmail 将其称为 [Gmail]/Spam。也可以使用原始文件夹名称。

完整参数和返回值结构： 工具参考。

使用 pip 安装

如果你已经安装 Python 3.11+，且不想运行安装程序：

pip install rubit-mcp-mail
rubit-mcp-mail install      # the same setup wizard, from the terminal

从源代码安装

cd /path/to/rubit-mcp-mail
conda create -p ./.venv python=3.12 pip -y     # this machine has no python3-venv
./.venv/bin/python -m pip install -e .

然后配置账户，运行 rubit-mcp-mail auth <account> 和 rubit-mcp-mail doctor。Windows 版本和完整操作指南请参阅 从源代码安装。

设置邮箱

Microsoft 已弃用 Outlook.com 的基本身份验证，因此 Outlook 需要注册一个免费的 Azure 应用——共七个步骤，只需设置一次，详见 设置 Outlook。 其他邮箱只需使用应用密码：

[accounts.personal]
provider = "generic"
email    = "[email protected]"
host     = "imap.fastmail.com"

已知主机：Gmail 为 imap.gmail.com，Fastmail 为 imap.fastmail.com， iCloud 为 imap.mail.me.com，Yahoo 为 imap.mail.yahoo.com。Gmail 和 iCloud 需要使用应用专用密码，而非登录密码。

无法注册自己的 Azure 应用？

如果你的 Microsoft 账户确实无法注册应用，可以使用其他开源邮件工具已为此共用的公共 客户端 ID——Thunderbird 的 9e5f94bc-e8a4-4e73-b8be-63364c29d753。将它填入 client_id 即可。授权界面会显示“Thunderbird”，并且由于该 ID 不受我们控制， Microsoft 可能会轮换它。详情和注意事项： 无法注册自己的应用？。

权限

你可以在 config.toml 中使用 disabled_tools，或在设置窗口的“权限”选项卡中取消勾选， 禁止特定账户使用任何账户级工具。被阻止的调用会向模型返回普通的 Error: ... 字符串， 而不是悄无声息地失败。请参阅 权限。

在 Claude 中注册

claude mcp add rubit-mail --scope user -- "$(pwd)/.venv/bin/rubit-mcp-mail" serve

Claude Desktop 需要使用 JSON 条目；在 Linux 上，还需要显式传递会话环境，否则将无法访问 密钥环——在 Claude 中注册 介绍了这两项配置， 故障排除 则提供了日志。

Agent 技能

skills/rubit-mail/SKILL.md 会告诉 Agent 何时使用邮件工具、 如何串联使用这些工具，并提醒它服务为只读模式，且邮件内容不可信。对于 Claude Code，请将其 复制到你的用户技能目录（或项目的 .claude/ 技能目录）中：

mkdir -p ~/.claude/skills && cp -r skills/rubit-mail ~/.claude/skills/

其他能读取 SKILL.md 文件的 Agent 也可以采用相同方式。请参阅 Agent 技能。

开发

ruff check .
ruff format --check .
pyright
pytest -q

这些检查与 CI 运行的检查相同。提交消息遵循 Conventional Commits 规范，并用于驱动自动 版本管理——请参阅 CONTRIBUTING.md 和 AGENTS.md。构建安装程序和添加提供方的相关说明见 贡献指南。

网站

website/ 存放文档网站（Nuxt），由 .github/workflows/deploy-website.yml 部署到 GitHub Pages。它是文档的权威来源； 此 README 刻意保持简短。

重要

网站提交不得使用 feat: 或 fix:。python-semantic-release 解析的是提交 类型，而非范围，因此 feat(site): … 会导致 Python 包版本递增并发布安装程序。请使用 docs(site):、 chore(site): 或 ci(site):。

目录结构

src/rubit_mcp_mail/
  server.py        MCP tool definitions
  __main__.py      CLI: serve | install | auth | doctor | gui
  installer.py     setup wizard: writes config, signs in, registers with Claude
  installer_gui.py the setup window (tkinter), falling back to the terminal
  shortcuts.py     Start Menu / Desktop / .desktop entries for the GUI
  claude_registration.py  claude_desktop_config.json / `claude mcp add`
  session.py       wires config + auth + backend; attachment path safety
  config.py        TOML config -> Account models
  diagnostics.py   the doctor checks, as data (shared by the CLI and the GUI)
  permissions.py   registry of per-account-toggleable tool names
  config_editor.py every write to config.toml: comment-preserving, validated
  config_gui.py    the settings window (tkinter): accounts, permissions, doctor
  providers.py     provider profile registry
  secrets.py       keyring with 0600-file fallback
  models.py        pydantic models + message handles
  mime.py          BODYSTRUCTURE walking, decoding, HTML->text
  backends/
    base.py        MailBackend protocol
    imap.py        the IMAP implementation
  auth/
    password.py         app passwords
    oauth_microsoft.py  MSAL device-code flow
skills/rubit-mail/SKILL.md  agent skill: when and how to use the tools
website/           the documentation site (Nuxt); see "The website" above

发布

每次合并到 main 都会准备一个发布 PR，其中仅包含 pyproject.toml 和 CHANGELOG.md 的差异；维护者手动合并该 PR，从而发布预发布版本并构建安装程序； 随后手动触发 promote-release.yml，移除 -rc.N 后缀。人工合并至关重要——GitHub 不会为 GITHUB_TOKEN 执行的操作触发任何事件。完整流程见： CONTRIBUTING.md 和发布流程。

说明与限制

IMAP 搜索基于子字符串，邮件正文会截断至 20,000 个字符，且仅下载文本部分。Microsoft 正在积极收紧对第三方邮件的访问权限。详情请参阅 说明与限制。