proton-bridge-mcp
This server provides read-only access to a Proton Mail inbox via Proton Mail Bridge, enabling listing, searching, and retrieving messages. It can list all mailboxes/folders (e.g., INBOX, Archive, Sent), list recent messages from a specified mailbox (default INBOX, configurable limit up to 100), search messages by sender, subject, or body text with configurable result limit, and fetch the full parsed content (text/HTML) of a specific message by UID. Note: no sending, deleting, or modifying messages is possible.
Provides tools for reading and searching Proton Mail inbox through Proton Mail Bridge, including listing mailboxes, listing messages, searching by sender/subject/body, and fetching full message contents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@proton-bridge-mcp search my inbox for unread emails from my manager"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: proton-bridge-mcp
Features
list_mailboxes— list all folders/labelslist_messages— list recent messages in a mailboxsearch_messages— search by sender, subject, or body textget_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 modelmove_messages— move messages to another mailbox: trash, archive, restore to inbox, mark as spam, or file into any folderflag_messages— star/unstar or mark read/unreaddelete_messages— permanently delete (expunge); irreversible in Trash/Spam/Drafts, elsewhere Bridge turns it into a move to Trashmanage_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 UIDcreate_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 setupYou'll be asked for:
Bridge IMAP host/port (defaults:
127.0.0.1/1143) and SMTP port (default1025)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:
Connects to Bridge and performs the real IMAP
STARTTLSupgrade to fetch its certificate (noopenssldependency — a portable Node-native handshake)Prints the certificate's SHA-256 fingerprint for your own awareness
Verifies login actually works, validated strictly against that same pinned certificate
Writes
~/.config/proton-bridge-mcp/credentials.jsonandbridge-ca.pem, bothchmod 600, inside achmod 700directory
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-mcpCodex 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:
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_28Register 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.1.0Reason: if you've ever run
npm install -g @alpharomercoma/proton-bridge-mcpon the same machine, an unpinnednpxinvocation 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 |
| Config directory |
|
| Bridge IMAP/SMTP host | value from |
| Bridge IMAP port | value from |
| Bridge SMTP port (sending) | value from |
| Proton Mail address | value from |
| Bridge password | value from |
| Path to pinned cert 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), notrejectUnauthorized: 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=...toclaude mcp add(which lands in~/.claude.jsonand your shell history), the password lives only incredentials.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.
Available Tools
4 toolsget_messageGet message contentB
Fetch the full parsed content (text/html body) of a single message by UID.
Inputs: uid (required), mailbox.
list_mailboxesList mailboxesA
List all mail folders/mailboxes available on the Proton Mail account via Bridge.
Inputs: no named parameters.
list_messagesList recent messagesA
List the most recent messages in a mailbox (default INBOX), newest first.
Inputs: limit, mailbox.
search_messagesSearch messagesA
Search a mailbox by sender, subject, or body text.
Inputs: from, text, limit, mailbox, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct action: listing mailboxes, listing messages, searching messages, and fetching a single message. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern: list_mailboxes, list_messages, search_messages, get_message. The naming is predictable and uniform.
With 4 tools, the set is well-scoped for a focused read-only email access use case. Each tool serves a clear purpose and none are redundant.
The toolset covers the primary read workflow: enumerate mailboxes, list messages, search, and fetch full content. However, it lacks send, draft, or message mutation capabilities, which are common in email tools but may be intentionally omitted for a read-only bridge interface.
Maintenance
Related MCP Connectors
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Connect Gmail, iCloud Mail, Outlook, Yahoo Mail, Fastmail and other IMAP inboxes to ChatGPT, Claude and compatible AI assistants. Find emails by meaning across languages with semantic search. Ask AI to find customer conversations, summarize deadlines and draft follow-ups. Give a sales rep access to a shared outreach inbox or bring email into a compatible CRM. Share an iCloud custom-domain inbox with teammates without their own Apple ID or iCloud+ plan. Search results may be incomplete or stale; separate permissions control mail actions.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Private, EU-hosted email for AI agents over JMAP: read, search, reply, draft, organize, send.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Proton Mail via MCP, enabling AI agents to list accounts/folders, search messages, and read emails using Proton Mail Bridge's local IMAP server.MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read, organize, and send Proton Mail through the local Proton Bridge, with careful gating for sending and attachment access.252Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with a Proton Mail mailbox through Proton Bridge, supporting listing, searching, reading, sending, and organizing emails.-
- AlicenseBqualityBmaintenanceEnables AI assistants to read, search, send, reply, and organize ProtonMail emails through a local ProtonMail Bridge, with automatic Bridge discovery and pinned TLS verification.23LGPL 3.0