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 isend-to-end encrypted, and the only supported way for an external program toreach it is Proton Bridge, which signs in tothe account, performs all OpenPGP encryption and decryption locally, andre-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 protocolcode here at all — no SRP, no key handling, no PGP — which is deliberate: thoseare 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 or from another address on the account
`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 useBODY.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 orFolders/Work:77. IMAP UIDs are per-folder, so an ID is only valid while themessage stays where it was found; after move_email the old ID is dead and thetool 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 underFolders/ (exclusive) and Labels/ (non-exclusive). Tools accept anyreasonable spelling: inbox, junk → Spam, bin → Trash, all mail, aplain leaf name like Work → Folders/Work, or the full path. Search a wholemailbox 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 isgenerated 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, whichreports 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. Twoindependent auth layers, neither of which is this server's code:

Connector auth — authentik decides who may use the connector, enforced atthe 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. Messagehandling is tested against real imap_tools objects parsed from raw RFC822bytes, 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 comparewhole dates, so a time-of-day bound is applied client-side after fetching.
Attachment filtering happens after the fetch, because IMAP cannot search onit. 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 thanfailing obscurely.

Proton Mail MCP Server