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

Tool	What it does
`list_emails`	Recent messages in a folder, newest first, with optional date window and unread filter
`search_emails`	Search by sender, recipient, subject, body, free text, date range or attachments
`read_email`	One message in full, with the body flattened to text
`send_email`	Send a message, optionally as a threaded reply
`list_folders`	The mailbox's system folders, user folders and labels, with counts
`mark_email`	Mark a message read or unread
`move_email`	Move a message to another folder (moving to `trash` is how you delete)
`about`	What this server is
`check_auth_status`	Whether the mailbox is reachable through Bridge right now

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

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

Variable	Default	Notes
`PROTON_BRIDGE_USER`	required	Your Proton address
`PROTON_BRIDGE_PASSWORD`	required	Bridge's generated mail-client password
`PROTON_BRIDGE_HOST`	`127.0.0.1`
`PROTON_IMAP_PORT`	`1143`
`PROTON_SMTP_PORT`	`1025`
`PROTON_IMAP_SECURITY`	`starttls`	or `ssl`, `none`
`PROTON_SMTP_SECURITY`	`starttls`	or `ssl`, `none`
`PROTON_TLS_VERIFY`	`false`	Bridge's cert is self-signed by its own CA
`PROTON_SEND_FROM`	= `PROTON_BRIDGE_USER`	From header, if sending as another address
`PROTON_TIMEOUT`	`60`	Seconds
`MCP_TRANSPORT`	`stdio`	`http` for the hosted deployment
`MCP_HOST` / `MCP_PORT` / `MCP_PATH`	`127.0.0.1` / `8000` / `/mcp`	HTTP transport only

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:

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