protonmail-mcp-server

A Model Context Protocol server that lets Claude read, search, and send email through a locally running ProtonMail Bridge.

Requirements

• ProtonMail Bridge installed and signed in
• Python 3.10+
• uv

Installation

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=bridge-generated-password  # from the Bridge app, not your Proton password

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "protonmail": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/protonmail-mcp-server", "protonmail-mcp"],
      "env": {
        "PROTONMAIL_USERNAME": "user@proton.me",
        "PROTONMAIL_PASSWORD": "bridge-password"
      }
    }
  }
}

Claude Code

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

Then set credentials in ~/.claude.json under the protonmail entry's env field.

Available tools (16)

Reading

Tool	Description
list_mailboxes	List all folders and labels (with type: folder|label)
get_mailbox_status	Count messages and unread in a folder
list_emails	List emails with metadata — paginated (page, page_size, has_more)
get_email	Fetch full email — supports body_format (full/text/stripped) and max_length
get_email_headers	Fetch headers only, no body (fast)
search_emails	Search by from/subject/date/unread — returns metadata, accepts ISO 8601 dates

Sending

Tool	Description
send_email	Send an email (to, subject, body, cc, bcc, reply_to)
reply_to_email	Reply — sets Re: prefix, In-Reply-To and References headers automatically
forward_email	Forward — sets Fwd: prefix and quotes original

Management

Tool	Description
mark_email_read	Mark as read
mark_email_unread	Mark as unread
move_email	Move to another folder
delete_email	Delete an email

Folders

Tool	Description
create_folder	Create a new folder
delete_folder	Delete a folder (must be empty)
rename_folder	Rename a folder

Testing

# Unit and BDD tests (no Bridge required)
uv run pytest tests/unit/ tests/features/ -v

# Integration tests (requires running Bridge + .env)
uv run pytest tests/integration/ -m integration -v

Or test interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector uv run protonmail-mcp

Open http://localhost:6274 → Connect → Tools.

Configuration

All settings use the PROTONMAIL_ prefix and can be set in .env or as environment variables:

Variable	Default	Description
PROTONMAIL_USERNAME	—	Your Proton email address
PROTONMAIL_PASSWORD	—	Bridge-generated password
PROTONMAIL_IMAP_HOST	127.0.0.1	IMAP host
PROTONMAIL_IMAP_PORT	1143	IMAP port
PROTONMAIL_SMTP_HOST	127.0.0.1	SMTP host
PROTONMAIL_SMTP_PORT	1026	SMTP port
PROTONMAIL_VERIFY_SSL	false	Enable SSL verification
PROTONMAIL_SMTP_CA_CERT	—	Path to Bridge cert for pinning

Technical notes

ProtonMail Bridge v3 exposes:

• IMAP on 127.0.0.1:1143 — plain TCP
• SMTP on 127.0.0.1:1026 — direct TLS with self-signed certificate

The IMAP connection is persistent (one per server session) with automatic reconnect on timeout. SMTP connects per send.

License

GNU General Public License v3.0 — see LICENSE.