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.

Prefer not to use a terminal?

On Ubuntu, the desktop setup assistant does all of this from a native application: it needs neither Python nor uv, and it configures Bridge, the plugin and the keyring for you. This command-line path stays fully supported, and the assistant never modifies an installation made this way.

Prerequisites

  • Linux with the official Proton Mail Bridge installed, signed in, and running.
  • A Proton plan that supports Bridge.
  • Python 3.11 or newer; CI tests every stable minor from 3.11 through 3.14.
  • uv.
  • A working Secret Service keyring such as gnome-keyring.

1. Install a reviewed release

uv tool install proton-safe-mcp==2.3.0

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. These exports affect only the current shell and processes started from it. If ChatGPT desktop or another graphical client starts the server, follow that client's environment procedure instead; for the Proton Safe plugin, use the OpenAI plugin guide.

To draft as one of your account's other Proton addresses, add the optional sender allowlist in the same environment:

export PROTON_BRIDGE_ALIASES="billing@example.com,legal@example.com"

Entries are bare comma-separated addresses; see Sender addresses for the exact rules.

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. Diagnose the local setup

Run the non-destructive diagnostic before registering the server:

proton-safe-mcp doctor

The report verifies the runtime, platform, configuration, private state directory, credential lookup, and authenticated Bridge connection. It does not print credentials, email addresses, mailbox counts, or message content, so its output can be safely attached to installation feedback.

5. 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"
  }
}

PROTON_BRIDGE_ALIASES belongs in this same env block when it is configured.

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.

6. 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.