protonmail-mcp-server

A Model Context Protocol server that lets Claude (or any MCP client) read, search, organise, draft and send email through a locally running ProtonMail Bridge.

It is built for being driven by an LLM: every email is treated as untrusted input, nothing is ever marked as read by accident, deletion goes to Trash, drafts are the preferred way to "send", and an operator can restrict what the model may do (read-only mode, draft-only mode, recipient allow-list, rate limits, audit log).

What you get:

• 29 tools — reading, search and conversations, sending and replying, drafts, attachments, labels and stars, bulk operations, folders, and new-mail checks.
• MCP resources for mailboxes and individual emails, with subscriptions that notify the client about new mail.
• Prompts for common tasks (summarise unread mail, triage, draft a reply, clean up newsletters).
• New mail via IMAP IDLE on dedicated connections, without polling.

Tool descriptions, server instructions, prompts and error messages are written in Swedish; models handle this fine, and the tool names and parameters are English.

What changed in each release is in CHANGELOG.md. Upgrading from 0.2.0? Version 0.3.0 has breaking changes (Python 3.12+, mailbox required for UID-based tools, new search_emails and list_mailboxes response formats and more) — read its upgrade notes first.

Requirements

• ProtonMail Bridge v3, installed and signed in
• Python 3.12 or newer
• uv

Installation

There are two ways to install the server. Most people want the first.

| | Install as a tool | Run from a clone | |---|---|---| | For | Using the server with Claude | Changing the code, running the tests | | Command | protonmail-mcp on your PATH | uv --directory /path/to/clone run protonmail-mcp | | Credentials | In the client's MCP configuration (env) | In .env in the clone | | Upgrade | Re-run the install command with the new tag | git pull && uv sync |

Before either: install and start ProtonMail Bridge, sign in, and copy the Bridge password for your account from the Bridge app (it is not your Proton password).

Option 1: install as a tool (recommended)

1. Install a released version with uv. uv installs it in its own environment with the dependency versions it was tested with, and puts protonmail-mcp in ~/.local/bin:

uv tool install --python 3.12 "git+https://github.com/mattias242/protonmail-mcp-server@v0.4.0"

If uv says ~/.local/bin is not on your PATH, run uv tool update-shell and open a new terminal. Check the installation with uv tool list; it should show protonmail-mcp v0.4.0.

2. Add it to your client with your Proton address and the Bridge password. Use the full path to the command (which protonmail-mcp, usually /Users/<you>/.local/bin/protonmail-mcp on macOS), because Claude Desktop does not read your shell's PATH.

Claude Code:

claude mcp add protonmail -s user \
  -e PROTONMAIL_USERNAME=user@proton.me \
  -e PROTONMAIL_PASSWORD=brid…[redacted] \
  -- /Users/<you>/.local/bin/protonmail-mcp

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop:

{
  "mcpServers": {
    "protonmail": {
      "command": "/Users/<you>/.local/bin/protonmail-mcp",
      "env": {
        "PROTONMAIL_USERNAME": "user@proton.me",
        "PROTONMAIL_PASSWORD": "brid…[redacted]"
      }
    }
  }
}

Any other setting (see Configuration) goes in the same env object, or as another -e before --. The client stores these values in its configuration file in plain text, readable by your user account.

3. Check it works: in Claude Code, run /mcp and look for protonmail as connected. In either client, ask Claude to list your mail folders; it should call list_mailboxes and show the folders from Bridge.

Upgrading from an earlier version: run the install command for the new version with --force, then restart Claude Desktop, or reconnect the server in Claude Code with /mcp. Your client configuration stays as it is.

uv tool install --force --python 3.12 "git+https://github.com/mattias242/protonmail-mcp-server@v0.4.0"

Read the upgrade notes for every version you skip in CHANGELOG.md first. To remove the server: uv tool uninstall protonmail-mcp and delete it from the client's configuration.

Option 2: run from a clone (development)

git clone https://github.com/mattias242/protonmail-mcp-server
cd protonmail-mcp-server
uv sync
cp .env.example .env

Edit .env:

PROTONMAIL_USERNAME=user@proton.me
PROTONMAIL_PASSWORD=brid…[redacted]  # from the Bridge app, not your Proton password

The server reads .env from the project root even when it is started from another directory; a .env in the current working directory takes precedence, and environment variables override both. Keep .env out of version control (it is in .gitignore).

Claude Code:

claude mcp add protonmail -s user -- uv --directory /path/to/protonmail-mcp-server run protonmail-mcp

Claude Desktop:

{
  "mcpServers": {
    "protonmail": {
      "command": "uv",
      "args": ["--directory", "/path/to/protonmail-mcp-server", "run", "protonmail-mcp"]
    }
  }
}

Replace /path/to/protonmail-mcp-server with the absolute path to your clone. If Claude Desktop cannot find uv, use its full path (which uv) as "command". The server can also be started with python -m protonmail_mcp (or python -m protonmail_mcp.server) inside the project environment.

To try the server interactively, use the MCP Inspector and open the URL it prints:

npx @modelcontextprotocol/inspector uv --directory /path/to/protonmail-mcp-server run protonmail-mcp

Troubleshooting

• The server does not start, or /mcp shows it as failed: run the command from the client configuration in a terminal with the same PROTONMAIL_* variables. The error is printed on stderr (for example a missing PROTONMAIL_USERNAME).
• "Kan inte nå ProtonMail Bridge" (cannot reach Bridge): Bridge is not running or not signed in, or PROTONMAIL_IMAP_HOST/PROTONMAIL_IMAP_PORT do not match the ports shown in Bridge's settings (default IMAP 1143, SMTP 1026).
• Login fails: use the password Bridge shows for the account, not your Proton password.
• ModuleNotFoundError: mcp.server.fastmcp: an old version (0.3.0) installed against mcp 2.x. Upgrade as above.

Tools

UIDs are per mailbox (see Security model). Every tool that takes a uid also requires the mailbox the UID came from; listing and search tools default to INBOX. Tools marked "up to 100 UIDs" accept a single UID or a list and return {"ok": [...], "failed": [{"uid", "error"}]} for a list.

Effect is taken from each tool's MCP annotations: read-only changes nothing; writes changes the mailbox (or, for get_attachment, a local file) but loses nothing; destructive moves, removes or replaces something; sends delivers email to other people and cannot be undone.

Reading

| Tool | What it does | Effect | |------|--------------|--------| | list_mailboxes | All folders and labels with name, type (system, folder, label, container), selectable and special_use | read-only | | get_mailbox_status | Number of messages and unread messages in a folder | read-only | | list_emails | Metadata for the emails in a folder, newest first, paginated (page, page_size 1–100) | read-only | | get_email | One email: decoded headers, body (body_format text/stripped/full, max_length), attachment list, plus the safety fields described below | read-only | | get_email_headers | Raw header values (not RFC 2047-decoded) without the body — fast | read-only |

Search and conversations

| Tool | What it does | Effect | |------|--------------|--------| | search_emails | Filter by sender, recipient, Cc, subject, date range, full text, body, unread, starred, answered, size and attachments (all filters combined with AND); returns metadata, newest first, up to 200 hits | read-only | | get_thread | The whole conversation an email belongs to, rebuilt from Message-ID/In-Reply-To/References across All Mail (received and sent) | read-only |

Sending and replying

| Tool | What it does | Effect | |------|--------------|--------| | send_email | Send a new email (to, cc, bcc, reply-to, optional HTML, attachments from the attachment directory) | sends | | reply_to_email | Reply (or reply all) with Re:, In-Reply-To, References and the original quoted | sends | | forward_email | Forward with Fwd:, the original inline (text and HTML) and all its attachments | sends |

Drafts

Drafts are the recommended workflow: the model writes, a human reviews in Proton (or approves send_draft).

| Tool | What it does | Effect | |------|--------------|--------| | create_draft | Save a new email as a draft in Drafts — built exactly like send_email, nothing is sent | writes | | create_reply_draft | Save a reply as a draft (same recipients, threading and quoting as reply_to_email) | writes | | create_forward_draft | Save a forward as a draft (same content and attachments as forward_email) | writes | | update_draft | Replace a draft with a new version; keeps threading headers and attachments, moves the old version to Trash | destructive | | send_draft | Send a draft exactly as it is stored in Drafts (including edits made in Proton) to the recipients get_email shows, then remove it | sends |

Attachments

| Tool | What it does | Effect | |------|--------------|--------| | get_attachment | Save an attachment to the attachment directory (save=true, default) or return it inline as text/base64 up to PROTONMAIL_ATTACHMENT_MAX_INLINE_BYTES; the mailbox is not changed | writes |

Files to send are given as names inside the attachment directory via the attachments parameter of send_email, reply_to_email and forward_email (at most 20 files and 25 MB in total).

Managing, labels and bulk operations

| Tool | What it does | Effect | |------|--------------|--------| | mark_email_read | Mark as read — up to 100 UIDs | writes | | mark_email_unread | Mark as unread — up to 100 UIDs | writes | | flag_email | Star (sets \Flagged, which is Proton's Starred) — up to 100 UIDs | writes | | unflag_email | Remove the star — up to 100 UIDs | writes | | add_label | Add a label (Labels/…); the email stays in its folder — up to 100 UIDs | writes | | remove_label | Remove a label without touching the email otherwise — up to 100 UIDs | destructive | | move_email | Move to another folder (INBOX, Archive, Spam, Trash, Folders/…) — up to 100 UIDs | destructive | | delete_email | Move to Trash; permanent=true deletes for good, only from Trash (or Drafts) — up to 100 UIDs | destructive |

Folders

| Tool | What it does | Effect | |------|--------------|--------| | create_folder | Create a folder (Folders/Name) or label (Labels/Name) — the prefix is required | writes | | delete_folder | Delete your own folder or label; refused if it holds mail or subfolders unless force=true | destructive | | rename_folder | Rename your own folder or label (same prefix on both names) | destructive |

New mail

| Tool