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 (specifically npx). 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: proton-mail-mcp

Install

pip install proton-bridge-mcp
# or
uvx proton-bridge-mcp

Setup

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-setup

Register with an MCP client

Claude Code:

claude mcp add proton-mail -s user -- proton-bridge-mcp

Claude 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_28

Then register the server:

codex mcp add proton-mail -- uvx proton-bridge-mcp

uvx 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.