Skip to content

Getting started

This guide installs Proton Safe MCP from a reviewed release and registers its local STDIO server with an MCP-compatible client.

Prerequisites

  • Linux with the official Proton Mail Bridge installed, signed in, and running.
  • A Proton plan that supports Bridge.
  • Python 3.11 or newer.
  • uv.
  • A working Secret Service keyring such as gnome-keyring.

1. Install a reviewed release

uv tool install proton-safe-mcp==1.0.1

This installs the proton-safe-mcp command in uv's tool directory. Run command -v proton-safe-mcp to obtain its absolute path for graphical MCP clients that do not inherit your shell PATH.

To work on the project itself, clone the repository and use uv sync --extra dev instead.

2. Configure the local Bridge account

Open Proton Mail Bridge and note:

  • the Proton address configured in Bridge;
  • the local IMAP port;
  • the Bridge-generated IMAP password.

Set the address and port in the environment used by the CLI:

export PROTON_BRIDGE_USER="your-address@proton.me"
export PROTON_IMAP_PORT="1143"

The port shown by your Bridge installation is authoritative if it differs from 1143.

Use the Bridge credential only

Never enter your Proton account password, recovery phrase, 2FA secret, or hardware-key material. Proton Safe MCP only needs the installation-specific IMAP password generated by Bridge.

3. Store the credential

proton-safe-mcp setup

Enter the Bridge-generated IMAP password twice. It is stored under the service name proton-safe-mcp in the operating-system keyring.

4. Register the MCP server

Configure a local STDIO server in your MCP client. The exact file format varies by client, but the logical fields are:

{
  "name": "proton-safe",
  "transport": "stdio",
  "command": "/absolute/path/to/proton-safe-mcp",
  "args": ["serve"],
  "env": {
    "PROTON_BRIDGE_USER": "your-address@proton.me",
    "PROTON_IMAP_PORT": "1143"
  }
}

Do not put PROTON_BRIDGE_PASSWORD in a desktop client configuration. The server reads the credential from the keyring established by setup.

See Client setup for exact Claude Code, Cursor, and VS Code configurations.

5. Verify the connection

Start or reload the MCP client, then call mailbox_status. A successful result includes:

{
  "connected": true,
  "account": "your-address@proton.me",
  "inbox_messages": 42,
  "inbox_unread": 3
}

Next, call list_folders and list_messages to confirm read-only access. See Troubleshooting if the Bridge connection or keyring lookup fails.