📮 mailbridge

The email MCP server — give Claude, Codex, Cursor or any AI agent a real mail client for iCloud, Outlook, Gmail, QQ, 163 and any IMAP mailbox.

English | 简体中文

Search, read, draft, send, file, and bulk-export mail across every mailbox you own — in conversation. Written in pure Python with zero third-party dependencies: no pip install, no build step. If a Python 3.9+ interpreter exists, it runs.

Why

Most agent platforms' built-in connectors cover Gmail and Microsoft 365 work accounts. They do not cover personal iCloud, personal Outlook.com, QQ, 163, or your own IMAP server — and a search connector is not a mail client. mailbridge adds the missing operations: attachments, folders, real sending, bulk export. It speaks plain MCP over stdio, so the same server works in Claude, Codex, Cursor, Cline, Gemini CLI — anything that can launch an MCP server.

Provider	Method	Credential
iCloud Mail	IMAP/SMTP	App-specific password
Gmail	IMAP/SMTP	App password
QQ / 163 / 126	IMAP/SMTP	Authorization code (授权码)
Yahoo / Fastmail / custom	IMAP/SMTP	Provider app password
Outlook.com / Hotmail	Microsoft Graph	Free Entra app registration (OAuth)
Work / school Exchange	Microsoft Graph	Same registration + tenant consent

Quick start

git clone https://github.com/henry200803/mailbridge.git
python mailbridge/server/setup.py        # interactive wizard: add accounts, sign in, test

Then register the server with any MCP client:

// Claude Desktop (claude_desktop_config.json), Cursor, Cline, …
{
  "mcpServers": {
    "mailbridge": {
      "command": "python",
      "args": ["/path/to/mailbridge/server/server.py"]
    }
  }
}

# Claude Code
claude mcp add mailbridge -- python /path/to/mailbridge/server/server.py

# Codex CLI
codex mcp add mailbridge -- python /path/to/mailbridge/server/server.py

Cowork users: install the packaged .zip through the plugin installer instead — the bundled .mcp.json wires everything up.

Microsoft accounts need a (free) client ID

Microsoft retired password-based IMAP/SMTP, so Outlook.com / Hotmail and work/school mailboxes connect through Microsoft Graph with OAuth — which requires an Entra app registration. Most personal users don't have one yet. It is free (no Azure subscription), takes about five minutes in a browser, and one registration covers every Microsoft mailbox you own.

Follow the step-by-step guide — Registering a Microsoft app for mailbridge — then paste the resulting Application (client) ID into the setup wizard. The guide also covers tenant values, every common AADSTS error, and the university-mailbox consent problem. Your client ID stays in your local accounts.json; it is configuration for your own registration, and this repository ships none.

Tools

Tool	Purpose
`mail_list_accounts`	What mailboxes exist and whether they work
`mail_list_folders`	Folder tree with unread/total counts
`mail_search`	Filterable search across one or all accounts
`mail_get_message`	One message in full, HTML converted to text
`mail_get_thread`	The whole conversation
`mail_digest`	Cross-account unread review in one call
`mail_download_attachment`	Save an attachment to disk
`mail_export`	Bulk search results to CSV / JSON
`mail_draft`	Save a draft, threaded to a reply if asked
`mail_send`	Send immediately — requires `confirm=true`
`mail_mark`	Read/unread, flagged/unflagged, in bulk
`mail_move`	File messages into a folder
`mail_delete`	To Trash by default; permanent needs `confirm=true`
`mail_auth_status`	OAuth health for Microsoft accounts

Bilingual 🇬🇧🇨🇳

Tool descriptions, the setup wizard, and provider hints ship in English and Simplified Chinese. Switch any time:

python server/setup.py lang zh   # or: lang en

or set the MAILBRIDGE_LANG=zh environment variable in your MCP client config. English is the fallback for anything untranslated.

Cloud & portable mode

Credentials normally live in ~/.mailbridge/ on the machine running the server. On ephemeral machines — cloud sandboxes, containers — ship them inside the bundle instead: put a .mailbridge/ directory (the same accounts.json + tokens/) next to server/. Resolution order:

MAILBRIDGE_HOME env → ~/.mailbridge (when configured) → bundled .mailbridge/

so a bundle with baked-in credentials still defers to the local config on your own machine.

⚠️ A bundle containing credentials is a secret — never publish or share it. If one leaks, app passwords and the Entra registration are individually revocable.

Security

Credentials live only in ~/.mailbridge/accounts.json (mode 0600) on the machine running the server. Nothing is transmitted anywhere except to your mail provider.
No password ever passes through the conversation transcript — the wizard reads it with hidden input.
App passwords and the Entra registration are individually revocable: delete one and mailbridge is cut off instantly.
Sending and permanent deletion are gated behind an explicit confirm=true argument.

Known limits

Graph (Outlook/Exchange) attachments are supported up to 150 MB via chunked upload sessions; the provider's total-message-size limit still applies, as it does on every IMAP provider (typically 20–50 MB per message).
IMAP full-text search is server-side; some providers (notably QQ) silently return nothing for non-ASCII search terms — filter by sender or date instead.
mail_get_thread on IMAP matches normalised subjects rather than true threading headers; Graph accounts use real conversation ids.
Most universities block third-party apps until IT approves the Entra registration — that is tenant policy, not something mailbridge can route around.

Layout & tests

server/          MCP server (stdio JSON-RPC), IMAP + Graph backends, OAuth, i18n
skills/          agent workflow guides: mailbox setup & everyday mail handling
tests/           offline suite — no network, no credentials

python tests/test_mailbridge.py

Credits

Built by Sibo Huang. Developed with Claude Opus 5 (initial implementation, in Cowork) and Claude Fable 5 (live testing, bug fixes, bilingual i18n, release engineering).

mailbridge