The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Rubit MCP Mail listing page.
A read-only MCP server for reading your mail. Provider-agnostic: it speaks IMAP, so it works with Outlook.com, Gmail, Fastmail, iCloud, or a self-hosted server — the provider is a line of config, not a code change.
Read-only by construction. Folders are opened with EXAMINE, never SELECT,
and bodies are fetched with BODY.PEEK, so reading a message does not even mark
it as read. There are no send, move, delete, or flag code paths, and a test
asserts none are ever added.
📖 Full documentation: https://bgalmes.github.io/rubit-mcp-mail/
Download the installer for your system from the latest release and run it:
| System | File |
|---|---|
| Windows | rubit-mcp-mail-setup-windows.exe |
| Linux | rubit-mcp-mail-setup-linux — chmod +x it first |
Nothing needs to be installed beforehand: Python and every dependency are inside that one file. A window asks for your provider and email address, signs you in, and registers the mail server with Claude Desktop and Claude Code if it finds them — restart Claude Desktop afterwards and your mail is there. It also leaves you a rubit-mcp-mail Settings shortcut for everything you want to change later. No terminal, at any point.
There is no macOS installer; on a Mac, install from source (below).
A note on antivirus warnings. Windows Defender or Avast may flag this .exe.
This is a known false positive common to unsigned PyInstaller-built applications,
not anything this project's code does — see
the install guide
for what to do about it. Every published SHA-256 is listed on
the changelog.
| Tool | What it does |
|---|---|
list_accounts | Configured accounts and whether each is authenticated |
list_folders | Folders with normalized roles and unread counts |
list_messages | Browse a folder, newest first, paginated |
search_messages | Server-side search by text, sender, subject, date range, unread |
read_message | Full headers, body text, attachment metadata |
get_attachment | Save one attachment into the download directory |
Folders are addressed by role — inbox, sent, drafts, junk, trash,
archive — so you never need to know that Outlook calls it Junk Email while
Gmail calls it [Gmail]/Spam. Raw folder names work too.
Full arguments and return shapes: Tools reference.
If you already have Python 3.11+ and would rather not run an installer:
Then configure an account, rubit-mcp-mail auth <account>, and
rubit-mcp-mail doctor. The Windows variant and the full walkthrough are in
Install from source.
Microsoft has retired basic auth for Outlook.com, so Outlook needs a free Azure app registration — seven steps, done once, written out in Setting up Outlook. Everything else takes an app password:
Known hosts: Gmail imap.gmail.com, Fastmail imap.fastmail.com,
iCloud imap.mail.me.com, Yahoo imap.mail.yahoo.com. Gmail and iCloud require
an app-specific password, not your login password.
If your Microsoft account genuinely can't register one, you can use the public
client ID that other open-source mail tools already share for this purpose —
Thunderbird's, 9e5f94bc-e8a4-4e73-b8be-63364c29d753. Paste it in as
client_id. The consent screen will say "Thunderbird", and because the ID is
outside our control Microsoft could rotate it. Details and caveats:
Can't register your own app?.
Any account-scoped tool can be forbidden for a given account with
disabled_tools in config.toml, or by unticking a box on the settings
window's Permissions tab. A blocked call returns a plain Error: ... string to
the model rather than failing silently. See
Permissions.
Claude Desktop needs a JSON entry instead, and on Linux it needs the session environment passed explicitly or the keyring is unreachable — Register with Claude has both, and Troubleshooting has the logs.
Those are the same checks CI runs. Commit messages follow Conventional Commits and drive automatic versioning — see CONTRIBUTING.md and AGENTS.md. Building the installers and adding a provider are covered in Contributing.
website/ holds the documentation site (Nuxt), deployed to GitHub Pages by
.github/workflows/deploy-website.yml. It is the source of truth for the docs;
this README is deliberately the short version.
[!IMPORTANT] Website commits must not use
feat:orfix:.python-semantic-releaseparses the commit type, not the scope, sofeat(site): …would bump the Python package and cut an installer release. Usedocs(site):,chore(site):orci(site):.
Every merge to main prepares a release PR carrying only the pyproject.toml
and CHANGELOG.md diff; a maintainer merges it by hand, which publishes the
prerelease and builds the installers; promote-release.yml is dispatched
manually to drop the -rc.N suffix. The human merge is load-bearing — GitHub
raises no events for anything GITHUB_TOKEN does. Full flow:
CONTRIBUTING.md
and How releases work.
IMAP search is substring-based, bodies are truncated at 20,000 characters, only text parts are downloaded, and Microsoft is actively tightening third-party mail access. The details are in Notes and limits.