Skip to main content
Glama
alpharomercoma

proton-bridge-mcp

by alpharomercoma
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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-mcp-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 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 model

  • move_messages — move messages to another mailbox: trash, archive, restore to inbox, mark as spam, or file into any folder

  • flag_messages — star/unstar or mark read/unread

  • delete_messages — permanently delete (expunge); irreversible in Trash/Spam/Drafts, elsewhere Bridge turns it into a move to Trash

  • manage_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 UID

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

You'll be asked for:

  • Bridge IMAP host/port (defaults: 127.0.0.1 / 1143) and SMTP port (default 1025)

  • 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.1.0

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

PROTON_BRIDGE_MCP_HOME

Config directory

~/.config/proton-bridge-mcp

PROTON_BRIDGE_HOST

Bridge IMAP/SMTP host

value from credentials.json

PROTON_BRIDGE_PORT

Bridge IMAP port

value from credentials.json (default 1143)

PROTON_BRIDGE_SMTP_PORT

Bridge SMTP port (sending)

value from credentials.json (default 1025)

PROTON_BRIDGE_USER

Proton Mail address

value from credentials.json

PROTON_BRIDGE_PASSWORD

Bridge password

value from credentials.json

PROTON_BRIDGE_CA_PATH

Path to pinned cert PEM

<config dir>/bridge-ca.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), 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. 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 tools
get_messageGet message contentB

Fetch the full parsed content (text/html body) of a single message by UID.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYes
mailboxNoINBOX

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of disclosing behavioral traits. 'Fetch' implies a read operation, but the description does not address potential side effects (e.g., marking the message as read), authentication requirements, rate limits, or error behavior. This is a significant gap for a tool that accesses message content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly-worded sentence that conveys the core purpose without any filler. It is front-loaded with the verb and resource, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and no annotations, the description leaves important gaps: it doesn't describe the return format beyond 'parsed content', doesn't clarify the mailbox parameter, and offers no usage context. The simplicity of the tool raises the bar for clarity, and this description falls short of being fully self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions 'by UID', which references the uid parameter, but does not explain the mailbox parameter (default INBOX) or clarify the format/scope of UID. The description adds minimal semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetch') and resource ('single message'), clearly distinguishing the tool from siblings that list or search messages. The qualifiers 'full parsed content' and 'by UID' make the function unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is provided about when to use this tool versus alternatives like list_messages or search_messages. The description implies that a UID is needed, but it doesn't state that users should first list or search to obtain a UID, nor does it mention any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_mailboxesList mailboxesA

List all mail folders/mailboxes available on the Proton Mail account via Bridge.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It states the operation is to list all mailboxes, which is inherently read-only, but it does not disclose any additional behavioral details such as return format or whether system folders are included. This is acceptable for a simple listing tool but lacks extra context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no filler. It is front-loaded with the action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (zero parameters, no output schema), the description is complete enough to convey its purpose. It slightly lacks detail on what exactly is returned, but for a list operation this is not a critical gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the baseline for zero parameters is 4. The description adds no parameter details, but none are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('List') on a specific resource ('mail folders/mailboxes') with a defined scope ('available on the Proton Mail account via Bridge'). This clearly distinguishes it from sibling tools that operate on messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (to enumerate mail folders) and the resource is distinct from message-related siblings. However, it does not explicitly mention alternatives or exclusions, though the purpose is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_messagesList recent messagesA

List the most recent messages in a mailbox (default INBOX), newest first.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
mailboxNoMailbox path, e.g. INBOX, Archive, SentINBOX

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description provides some behavioral context (default mailbox, newest-first order) but does not disclose other traits such as pagination, return format, or whether messages are marked as read. The 'list' verb implies read-only, but that is not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that front-loads the core purpose with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two optional parameters and no output schema. The description covers the core purpose but omits details about the return structure and pagination behavior. It is minimally complete but not rich.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema describes the mailbox parameter but not limit. The description repeats the INBOX default but does not explain the limit parameter's semantics (e.g., maximum number of items). Since schema coverage is 50%, the description fails to compensate for the missing limit documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists recent messages in a mailbox, defaulting to INBOX, sorted newest first. It distinctly differentiates from sibling tools like list_mailboxes and get_message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when recent messages are needed, but does not explicitly mention alternatives or when not to use (e.g., search_messages for queries). No exclusion guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_messagesSearch messagesA

Search a mailbox by sender, subject, or body text.

ParametersJSON Schema
NameRequiredDescriptionDefault
fromNoFilter by sender address/name substring
textNoFilter by full text (body) substring
limitNo
mailboxNoINBOX
subjectNoFilter by subject substring

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of disclosing behavior. It states the searchable fields but does not disclose how matching works (e.g., substring vs exact, case sensitivity), whether filters combine with AND/OR, pagination behavior, ordering, or any other runtime characteristics. This is a significant gap for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that is front-loaded with the verb 'search' and clearly states the key attributes. Every word earns its place, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has moderate complexity with 5 parameters and no output schema or annotations. The description covers the basic search intent but omits details on return format, filter combination logic, and default behavior of limit and mailbox. It is adequate for basic use but lacks important contextual details for an agent to fully anticipate behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides descriptions for from, text, and subject, covering 60% of parameters. The description adds marginal value by grouping these into 'sender, subject, or body text', but it does not explain semantics for limit or mailbox, which have defaults but no descriptions in the schema. The description does not compensate for the incomplete parameter coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'search' with a clear resource 'a mailbox' and names the searchable attributes (sender, subject, body text). It clearly distinguishes the tool from sibling tools like list_messages and get_message, which list or fetch messages rather than filter by arbitrary fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used for searching a mailbox, which provides clear context. However, it does not explicitly state when to use this tool versus alternatives like list_messages or get_message, nor does it mention exclusions or prerequisites. Usage guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.1
    • First observedget_message
    • First observedlist_mailboxes
    • First observedlist_messages
    • First observedsearch_messages
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

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.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: list_mailboxes, list_messages, search_messages, get_message. The naming is predictable and uniform.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Proton Mail MCP Server

    fincher65
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to send, read, search, and organize email from Proton Mail accounts via SMTP and IMAP.
    67 npm
    MIT

  • proton-mcp-server

    QinZinn
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides 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

  • proton-bridge-mcp

    Considus
    A
    license
    A
    quality
    A
    maintenance
    Enables AI assistants to read, organize, and send Proton Mail through the local Proton Bridge, with careful gating for sending and attachment access.
    34
    1
    Apache 2.0

  • proton-mail-mcp

    graememeyer
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to interact with a Proton Mail mailbox through Proton Bridge, supporting listing, searching, reading, sending, and organizing emails.
    -