protonmail-mcp-server

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.