Proton Mail MCP Server

An MCP server exposing a Proton Mail mailbox to Claude — list, search, read, send, and file messages.

Proton Mail has no third-party REST API. Everything in a Proton mailbox is end-to-end encrypted, and the only supported way for an external program to reach it is Proton Bridge, which signs in to the account, performs all OpenPGP encryption and decryption locally, and re-exposes the decrypted mailbox as an ordinary IMAP/SMTP server on loopback.

This server therefore talks IMAP and SMTP to Bridge. There is no Proton protocol code here at all — no SRP, no key handling, no PGP — which is deliberate: those are the parts that break when Proton changes something.

Claude.ai
   │
   ▼  (authentik forward-auth at the reverse proxy)
proton-mail-mcp        FastMCP, HTTP on 127.0.0.1:8000/mcp
   │  IMAP 127.0.0.1:1143   (STARTTLS)
   │  SMTP 127.0.0.1:1025   (STARTTLS)
   ▼
Proton Bridge          SRP login + OpenPGP, Proton's own code
   │
   ▼
Proton

Bridge requires a paid Proton plan (Mail Plus or higher).

Tools

Listing, searching and reading never mark mail as read — the IMAP fetches use BODY.PEEK. read_email can opt in with mark_as_read=true.

Message IDs

Tools return IDs of the form <folder>:<uid>, e.g. INBOX:4821 or Folders/Work:77. IMAP UIDs are per-folder, so an ID is only valid while the message stays where it was found; after move_email the old ID is dead and the tool says so.

Folder names

Bridge puts Proton's system folders at the top level (INBOX, Sent, Drafts, Archive, Spam, Trash, All Mail) and namespaces user-created ones under Folders/ (exclusive) and Labels/ (non-exclusive). Tools accept any reasonable spelling: inbox, junk → Spam, bin → Trash, all mail, a plain leaf name like Work → Folders/Work, or the full path. Search a whole mailbox with folder="all mail".

Related MCP server: ProtonMail MCP Server

Setup

1. Proton Bridge

Install Bridge and sign in once, out of band. Headless:

protonmail-bridge --cli
>>> login
>>> info      # prints the address, ports, and the generated password

The password Bridge prints is not the Proton account password — it is generated per install for mail clients, and it is what goes in the config below.

2. Configure

cp .env.example .env
# fill in PROTON_BRIDGE_USER and PROTON_BRIDGE_PASSWORD

3. Install and run

python -m venv venv
venv/bin/pip install -r requirements.txt
venv/bin/python main.py

Check it can see the mailbox by calling the check_auth_status tool, which reports the account and INBOX counts, or names the specific problem if not.

Local use with Claude Code / Desktop

{
  "mcpServers": {
    "proton-assistant": {
      "command": "/path/to/proton-mail-mcp/venv/bin/python",
      "args": ["/path/to/proton-mail-mcp/main.py"]
    }
  }
}

Credentials come from .env; keep them out of the client config.

Hosted deployment

Runs on a Proxmox LXC behind a reverse proxy with authentik forward-auth, deployed by a GitHub Actions self-hosted runner on push to main. Two independent auth layers, neither of which is this server's code:

1. Connector auth — authentik decides who may use the connector, enforced at the proxy. The server binds to loopback and has no auth code by design.

2. Mailbox auth — Bridge holds the Proton credentials, signed in once.

Signing in to the connector does not grant mailbox access; they are unrelated.

See HANDOFF.md for the deployment runbook.

Tests

venv/bin/python -m pytest

The suite is fully offline — no Bridge, no credentials, no network. Message handling is tested against real imap_tools objects parsed from raw RFC822 bytes, so parsing, filtering, sorting and rendering are exercised for real.

Limitations

• Search is literal. IMAP SEARCH does case-insensitive substring matching, not ranked relevance. There is no stemming and no scoring.

• Date filters are day-granular on the server. IMAP SINCE/BEFORE compare whole dates, so a time-of-day bound is applied client-side after fetching.

• Attachment filtering happens after the fetch, because IMAP cannot search on it. Summaries infer attachments from Content-Type: multipart/mixed.

• No attachment download. Attachments are listed by name and size only.

• Bridge must be running. If it isn't, every tool says so plainly rather than failing obscurely.