proton-bridge-mcp
This server provides read-only access to your Proton Mail account via Proton Mail Bridge using IMAP.
list_mailboxes — Retrieve all available mail folders/mailboxes (e.g., INBOX, Sent, Archive).
list_messages — List recent messages in a specified mailbox (defaults to INBOX), newest first, with a configurable limit (1–100, default 20).
search_messages — Search within a mailbox (defaults to INBOX) by sender, subject, or body text, with a configurable result limit (1–100, default 20).
get_message — Fetch the full parsed content (text/html body) of a single email by its UID from a specified mailbox (defaults to INBOX).
Provides tools for reading and searching Proton Mail messages through the Proton Mail Bridge.
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 list my unread emails from today"
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 (Python wrapper)
A pip/uvx-installable wrapper around proton-bridge-mcp, an MCP server for reading and searching Proton Mail via Proton Mail Bridge.
This package contains no Python implementation. It's a thin shim that execs into the real Node.js implementation via npx. It exists so Python-oriented MCP tooling (uvx, pipx, pip install) can install and run it without needing to know it's Node underneath.
Unofficial, community project. Not affiliated with or endorsed by Proton AG.
Requirements
Node.js 18+ must be installed and on
PATH(specificallynpx). This wrapper cannot function without it — there is no pure-Python fallback.A Proton Mail plan that supports Bridge, with Proton Mail Bridge running
Related MCP server: protonmail-mcp-server
Install
pip install proton-bridge-mcp
# or
uvx proton-bridge-mcpSetup
Run the interactive setup wizard once (fetches and pins Bridge's TLS certificate, verifies login, writes credentials to ~/.config/proton-bridge-mcp/, chmod 600):
proton-bridge-mcp-setupRegister with an MCP client
Claude Code:
claude mcp add proton-mail -s user -- proton-bridge-mcpClaude Desktop / other MCP clients:
{
"mcpServers": {
"proton-mail": {
"command": "proton-bridge-mcp"
}
}
}Codex CLI:
Tested end-to-end against Codex CLI 0.146.0 via uvx, with a real Bridge connection and real tool calls. MCP support is behind an under-development feature flag as of 0.146.0 — enable it once:
codex features enable mcp_2026_07_28Then register the server:
codex mcp add proton-mail -- uvx proton-bridge-mcpuvx resolves and caches per exact version, so (unlike a bare npx invocation of the underlying npm package) it isn't at risk of silently picking up a stale global install — no version pinning needed here. All four tools are read-only IMAP calls and carry readOnlyHint annotations, so they run in both interactive codex and non-interactive codex exec without an approval prompt.
Note this wrapper always execs into whatever npm tag is latest for the underlying @alpharomercoma/proton-bridge-mcp package — see that repo's README for the one caveat that does apply if you've separately run npm install -g on the same machine.
Why does this exist separately from the npm package?
The actual server (list_mailboxes, list_messages, search_messages, get_message tools; TLS certificate pinning instead of disabled verification; the setup wizard) lives entirely in the Node.js project: https://github.com/alpharomercoma/proton-bridge-mcp. That's the canonical implementation, source of truth for behavior, and where issues/PRs about actual functionality belong. This repo only exists to make it reachable from pip/uvx workflows.
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 has a clearly distinct role: listing mailboxes, listing messages, searching messages, and fetching a single message. No overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern (list_mailboxes, list_messages, search_messages, get_message) with uniform snake_case style.
Four tools is well-scoped for a read-only email client, covering the core needs without unnecessary bloat or unclear additions.
The tool set covers the primary read operations (list, search, get) but lacks write operations like send, delete, or mark as read, which are expected in a full email workflow.
Maintenance
Related MCP Connectors
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Your mailbox for MCP clients: search, read, draft, send, rules and notes. Sending is off by default.
MCP server for MailTempo's public free temporary email inboxes.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceA read-only MCP server that connects to Proton Mail via Proton Bridge, enabling AI assistants to search, list, and read emails securely without leaving your machine.442 npm1MIT
- AlicenseAqualityBmaintenanceMCP server for reading, searching, and sending ProtonMail emails via the ProtonMail Bridge.293GPL 3.0
- AlicenseAqualityBmaintenanceAn MCP server that enables AI assistants to read and search Proton Mail messages through a locally running Proton Mail Bridge. It provides tools like list_folders, list_messages, search_messages, get_message, and get_attachment.29284 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that reads, searches, organizes, and deletes Proton Mail through the local Proton Mail Bridge, with read-only mode and sender authentication checks. It cannot send mail.105 npmMIT