Skip to main content
Glama
proton-bridge-mcp

proton-bridge-mcp

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: protonmail-mcp-server

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.

Available Tools

4 tools
get_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

    A3.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: listing mailboxes, listing messages, searching messages, and fetching a single message. No overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (list_mailboxes, list_messages, search_messages, get_message) with uniform snake_case style.

    Tool Count5/5

    Four tools is well-scoped for a read-only email client, covering the core needs without unnecessary bloat or unclear additions.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      4
      42 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      29
      284 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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 npm
      MIT