Skip to content

Installation

Requirements

  • macOS (Apple Silicon or Intel)
  • A paid Proton plan (Proton Mail Bridge requires Mail Plus, Proton Unlimited, or a business plan)
  • Homebrew
  • uv — brew install uv (it manages the right Python version automatically)
  • Claude Code and/or the Claude Desktop app

Setup

1. Install and configure Proton Mail Bridge

brew install --cask proton-mail-bridge

Open Proton Mail Bridge, sign in to your Proton account, and leave it running (it auto-starts at login). Then open Bridge → Settings → your account → Mailbox details and note:

  • your IMAP username (usually your Proton email address)
  • the Bridge-generated password (this is not your Proton password)
  • the Hostname and Port — the server defaults to Bridge's standard 127.0.0.1:1143 (IMAP) and 127.0.0.1:1025 (SMTP), so you normally don't set anything. But confirm they match on this screen — Bridge lets you change the ports (and may pick a different one if the default is taken). If yours differ, add --env PROTONMCP_IMAP_PORT=… / PROTONMCP_SMTP_PORT=… to the registration in step 4 (the host stays loopback); otherwise you'll get a confusing "connection refused".

2. Install the Proton Pass CLI and log in

The server never stores your Bridge password itself — it reads it on demand from Proton Pass through the official CLI.

brew install protonpass/tap/pass-cli
pass-cli login

pass-cli login opens your browser for Proton's web login; approve it there and the CLI stores an authenticated session locally (under ~/Library/Application Support/proton-pass-cli/). The session lasts a long time but does eventually expire — when a mail tool later reports "Proton Pass session expired", just run pass-cli login again; the server picks it up without a restart.

Confirm the session works:

pass-cli vault list

Advanced: instead of a full login you can use a scoped Personal Access Token (pass-cli login --pat pst_…) created in Proton Pass settings, so the CLI session can only see the vault(s) you grant it. Check the scope carefully — verify the token can't write vaults you didn't intend.

3. Create the vault and store the Bridge password

By default the server looks for a vault named Agent containing a login item titled proton-bridge. A dedicated vault for agent-readable secrets is deliberate: it limits what any AI tooling can see to exactly the secrets you put there. (To use an existing vault instead, e.g. Personal, set PROTONMCP_PASS_VAULT in step 5 — then skip the vault creation.)

Create the vault — either from the terminal:

pass-cli vault create --name Agent

or in the Proton Pass app: sidebar → Vaults → Create vault → name it Agent.

Store the Bridge password — in Bridge, click the copy icon next to "Use this password" (Settings → your account → Mailbox details), then within a few seconds:

pass-cli item create login --vault-name Agent --title proton-bridge \
  --username you@example.com --password "$(pbpaste)"
  • --username — your Bridge IMAP username (usually your Proton address)
  • --password "$(pbpaste)" — pastes straight from the clipboard, so the password never appears in your terminal or shell history

Prefer the app? Create a Login item in the Agent vault with title proton-bridge, username = Bridge IMAP username, password = the Bridge password. The names must match exactly (or set PROTONMCP_PASS_ITEM).

Verify the server will find it (prints the username, never the password):

pass-cli item view --vault-name Agent --item-title proton-bridge --field username

4. Register with Claude Code

No clone, no install — uvx fetches the package from PyPI and runs it in an isolated environment (with the right Python) automatically:

claude mcp add --scope user proton-mail \
  --env PROTONMCP_USERNAMES=you@example.com \
  -- uvx mcp-proton-email

--scope user makes it available in every project. Replace the address with your Bridge IMAP username. To pin a version: uvx mcp-proton-email@0.1.0.

5. Approve the one-time Keychain prompt

The first time the server reads your secret, macOS shows a dialog: "pass-cli wants to use your confidential information stored in 'ProtonPassCLI' in your keychain."

Enter your Mac login password and click Always Allow. This is required — it lets the server read the Bridge password headlessly in future sessions. (Plain "Allow" works once but re-prompts every time; if the prompt appears while no one is watching, pass-cli looks like it is hanging.)

6. Verify

claude mcp list        # proton-mail should show ✔ Connected

Start a new Claude Code session and ask: "check my Proton inbox".

Claude Desktop app

The Desktop app uses its own config file. Add this to ~/Library/Application Support/Claude/claude_desktop_config.json under mcpServers:

"proton-mail": {
  "command": "/opt/homebrew/bin/uvx",
  "args": ["mcp-proton-email"],
  "env": { "PROTONMCP_USERNAMES": "you@example.com" }
}

The command must be an absolute path — GUI apps launch with a minimal PATH that doesn't include Homebrew, so a bare uvx won't be found. Get yours with which uvx (commonly /opt/homebrew/bin/uvx on Apple Silicon, /usr/local/bin/uvx on Intel). Then fully quit the app (⌘Q) and reopen it; MCP servers load only at launch.

Prefer a fixed, upgrade-when-you-say-so install instead of uvx's latest-on-cold-cache behavior? Install it as a uv tool:

uv tool install mcp-proton-email     # -> ~/.local/bin/mcp-proton-email
uv tool upgrade mcp-proton-email     # when you want to update

and use "command": "/Users/<you>/.local/bin/mcp-proton-email" with no args.