proton-bridge-mcp

An MCP server that lets AI assistants (Claude Code, Claude Desktop, and other MCP clients) read and search your Proton Mail inbox 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.

Related MCP server: mcp-imap-server

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 the full parsed body of a message by UID

Read-only. There is intentionally no send_message tool in this version.

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)

• 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/proton-bridge-mcp@1.0.3

   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 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 all read-only IMAP calls, tagged with readOnlyHint annotations for exactly this reason.

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):

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. Keep changes scoped and avoid adding write/send capabilities without discussion — this project intentionally stays read-only for now.

License

MIT — see LICENSE.