proton-bridge-mcp

An MCP server that lets AI assistants (Claude Code, Claude Desktop, and other MCP clients) read, search, organize, and send Proton Mail through Proton Mail Bridge.

Unofficial, community project. Not affiliated with or endorsed by Proton AG.

Why Bridge, and why this exists

Proton Mail doesn't expose a public IMAP/SMTP API directly — Proton Mail Bridge runs locally, decrypts your mail, and re-exposes it as standard IMAP/SMTP on 127.0.0.1. That's the only supported way to speak IMAP to a Proton Mail account programmatically.

Bridge's local IMAP/SMTP listener uses a self-signed TLS certificate generated per install. Most quick-start IMAP MCP servers handle this by disabling certificate verification (rejectUnauthorized: false) — which defeats the purpose of TLS. This server instead pins the exact certificate Bridge presents at setup time and validates every connection against it, so a certificate swap (e.g. from another process impersonating Bridge on your machine) is still detected and rejected.

Features

• list_mailboxes — list all folders/labels
• list_messages — list recent messages in a mailbox
• search_messages — search by sender, subject, or body text
• get_message — fetch headers, plain-text body, flags, and attachment metadata for a message by UID (does not mark it read). All read tools label returned mail as untrusted data, since a hostile email could try to instruct the model
• move_messages — move messages to another mailbox: trash, archive, restore to inbox, mark as spam, or file into any folder
• flag_messages — star/unstar or mark read/unread
• delete_messages — permanently delete (expunge); irreversible in Trash/Spam/Drafts, elsewhere Bridge turns it into a move to Trash
• manage_mailbox — create, rename, or delete a folder (Folders/...) or label (Labels/...)
• send_message — send an email via Bridge SMTP, optionally as a threaded reply to a UID
• create_draft — compose the same way but save to Drafts instead of sending

The first four tools are read-only and carry readOnlyHint. The rest modify your mailbox or send mail and are annotated as writes (readOnlyHint: false, plus destructiveHint on everything except send_message and create_draft, since clearing a flag or moving/deleting mail undoes existing state), so MCP clients that gate on annotations will prompt before running them.

Every mailbox argument (and move_messages's destination, and reply_mailbox) accepts either an alias (inbox, trash, archive, spam, sent, drafts) or an exact mailbox path from list_mailboxes. Aliases resolve through the IMAP special-use attributes Bridge advertises (\Trash, \Archive, ...), with a fallback to the conventional folder name. flag_messages takes flag: "starred" | "read" and a boolean value; Proton's star is the IMAP \Flagged flag. move_messages, flag_messages, and delete_messages accept a list of up to 100 UIDs (from list_messages or search_messages), so you can act on many messages in one call.

send_message and create_draft take to/cc/bcc (string or array), subject, text, and optional html. A recipient is required to send but optional for a draft. Pass reply_to_uid (and reply_mailbox if not INBOX) to reply: the recipient defaults to the original's Reply-To/From, the subject to Re: ..., and In-Reply-To/References are set so the reply threads correctly. Sending goes through Bridge's SMTP listener (default port 1025, STARTTLS) validated against the same pinned certificate as IMAP.

Prerequisites

• A Proton Mail plan that supports Bridge (Unlimited, Business, or legacy Professional/Visionary — Bridge requires a paid plan)
• Proton Mail Bridge installed, running, and logged in
• Node.js 18+
• An MCP client: Claude Code, Claude Desktop, or any other MCP-compatible client

Setup

1. Install

git clone https://github.com/alpharomercoma/proton-bridge-mcp.git
cd proton-bridge-mcp
npm install

(Once published to npm, this step will be optional — see Using via npx below.)

2. Run the setup wizard

npm run setup

You'll be asked for:

• Bridge IMAP host/port (defaults: 127.0.0.1 / 1143) and SMTP port (default 1025)
• Your Proton Mail address
• Your Bridge password — this is a Bridge-generated password shown in the Bridge app under your account, not your normal Proton account password

The wizard then:

1. Connects to Bridge and performs the real IMAP STARTTLS upgrade to fetch its certificate (no openssl dependency — a portable Node-native handshake)
2. Prints the certificate's SHA-256 fingerprint for your own awareness
3. Verifies login actually works, validated strictly against that same pinned certificate
4. Writes ~/.config/proton-bridge-mcp/credentials.json and bridge-ca.pem, both chmod 600, inside a chmod 700 directory

Nothing is written until login has been verified.

3. Register with your MCP client

Claude Code:

claude mcp add proton-mail -s user -- node /path/to/proton-bridge-mcp/bin/proton-bridge-mcp.mjs

(Use -- npx -y @alpharomercoma/proton-bridge-mcp instead — see Using via npx below.)

Claude Desktop / other MCP clients — add to your MCP config file:

{
  "mcpServers": {
    "proton-mail": {
      "command": "node",
      "args": ["/path/to/proton-bridge-mcp/bin/proton-bridge-mcp.mjs"]
    }
  }
}

Using via npx

Published on npm as @alpharomercoma/proton-bridge-mcp — skip the local clone entirely:

npx -y -p @alpharomercoma/proton-bridge-mcp proton-bridge-mcp-setup
claude mcp add proton-mail -s user -- npx -y @alpharomercoma/proton-bridge-mcp

Codex CLI:

Tested end-to-end against Codex CLI 0.146.0 (codex mcp add, real Bridge connection, real tool calls). Two things are Codex-specific and easy to miss:

1. Codex's MCP support is behind an under-development feature flag as of 0.146.0. Enable it once:

   codex features enable mcp_2026_07_28

2. Register the server with an exact, pinned version — not a bare npx -y @alpharomercoma/proton-bridge-mcp:

   codex mcp add proton-mail -- npx -y @alpharomercoma/[email protected]

   Reason: if you've ever run npm install -g @alpharomercoma/proton-bridge-mcp on the same machine, an unpinned npx invocation will silently prefer that stale global install over fetching the current version from the registry — no error, it just quietly runs old code. Pinning the version sidesteps this entirely. Bump the pinned version here when you upgrade.

Once registered, codex mcp get proton-mail should show enabled: true, and the read-only tools (list_mailboxes, list_messages, search_messages, get_message) work in both the interactive codex session and non-interactive codex exec runs without triggering an approval prompt — they're tagged with readOnlyHint annotations for exactly this reason. The write tools (everything after get_message) are not read-only, so expect an approval prompt for those depending on your client's policy.

Configuration reference

By default, config lives at ~/.config/proton-bridge-mcp/. Override the location or individual values with environment variables (useful for multiple accounts or containers):

| Variable | Purpose | Default | |---|---|---| | PROTON_BRIDGE_MCP_HOME | Config directory | ~/.config/proton-bridge-mcp | | PROTON_BRIDGE_HOST | Bridge IMAP/SMTP host | value from credentials.json | | PROTON_BRIDGE_PORT | Bridge IMAP port | value from credentials.json (default 1143) | | PROTON_BRIDGE_SMTP_PORT | Bridge SMTP port (sending) | value from credentials.json (default 1025) | | PROTON_BRIDGE_USER | Proton Mail address | value from credentials.json | | PROTON_BRIDGE_PASSWORD | Bridge password | value from credentials.json | | PROTON_BRIDGE_CA_PATH | Path to pinned cert PEM | <config dir>/bridge-ca.pem |

Environment variables always take precedence over the credentials file.

Security model

• No disabled TLS verification. The server validates every connection against the certificate pinned during setup (tls.ca), not rejectUnauthorized: false.
• Trust-on-first-use, like SSH. The one moment we can't validate against anything is fetching the certificate itself during setup — the same bootstrap problem SSH solves by showing you a host-key fingerprint on first connect. Bridge only listens on 127.0.0.1, so this step can't be intercepted over the network; only another process already running as you on the same machine could tamper with it, and at that point your credentials file is equally exposed regardless of TLS.
• Credentials never touch the MCP client's own config. Rather than passing -e PROTON_BRIDGE_PASSWORD=... to claude mcp add (which lands in ~/.claude.json and your shell history), the password lives only in credentials.json, chmod 600, outside any repo or synced config.
• Rotate the Bridge password if it's ever been pasted into a chat, terminal share, or committed by accident. Bridge passwords are cheap to regenerate (Bridge app → account → "Generate new password") and don't touch your actual Proton account password.

Troubleshooting

Missing Proton Bridge "host" / "user" / "password" — run npm run setup (or npx -p @alpharomercoma/proton-bridge-mcp proton-bridge-mcp-setup) first, or set the PROTON_BRIDGE_* env vars.

No pinned Bridge certificate found — same as above; the setup wizard writes bridge-ca.pem alongside the credentials.

Login fails during setup — double check you're using the Bridge-generated password (visible in the Bridge app), not your Proton account password. Also confirm Bridge is running and unlocked.

Certificate fingerprint changes unexpectedly — this happens if you reinstall Bridge or reset its config (it regenerates its cert). Re-run npm run setup to re-pin. If you didn't reinstall Bridge and the fingerprint changed anyway, treat that as suspicious and investigate before continuing.

Contributing

Issues and PRs welcome. Run npm run lint, npm test, and npm run build (syntax check plus a dry-run npm pack) before opening a PR; CI runs the same three on Node 18/20/22. Keep changes scoped. Anything that widens what the server can do to your mailbox (new write tools, attachments, bulk operations) should come with tests and a README note on its safety annotations.

License

MIT — see LICENSE.