Client setup

These configurations run Proton Safe MCP locally over STDIO. Complete Getting started first: Proton Mail Bridge must be running, the package must be installed, and the Bridge-generated IMAP password must already be stored with proton-safe-mcp setup.

Never configure the Proton password

The env blocks below contain only non-secret settings: the Proton address, the Bridge port, and the optional sender allowlist. Never add your Proton account password, recovery phrase, 2FA secret, hardware-key material, or even the Bridge-generated IMAP password. The server obtains the Bridge credential from the OS keyring.

Find the installed command before configuring a graphical client:

command -v proton-safe-mcp

Use the returned absolute path wherever an example shows /absolute/path/to/proton-safe-mcp.

Each example sets the two values the server needs. To draft as one of your account's other Proton addresses, add PROTON_BRIDGE_ALIASES alongside PROTON_BRIDGE_USER in the same place, as comma-separated bare addresses: see Sender addresses.

ChatGPT and Codex plugin

The repository includes a local marketplace and the proton-safe plugin. It can launch the same STDIO server directly in ChatGPT desktop and Codex while packaging the canonical mail-review and draft-preparation skills. This is the primary OpenAI setup when the client and Proton Mail Bridge run on the same machine.

The plugin is optional: ChatGPT desktop can also register the STDIO command directly under Settings → MCP servers, and that configuration is shared with Codex on the same host. Follow the dedicated OpenAI plugin guide for both paths. If the plugin is listed but has no tools, use the Ubuntu startup troubleshooting and FAQ before reinstalling it.

Use the tunnel only for ChatGPT web or to reach a different Bridge machine. Run Proton Mail Bridge and proton-safe-mcp together on that machine rather than exposing Bridge IMAP over the network.

Claude Code

Register the server at user scope so the configuration stays private and is available in all of your projects:

claude mcp add \
  --scope user \
  --env PROTON_BRIDGE_USER="your-address@proton.me" \
  --env PROTON_IMAP_PORT="1143" \
  --transport stdio \
  proton-safe \
  -- /absolute/path/to/proton-safe-mcp serve

Verify the connection:

claude mcp get proton-safe
claude mcp list

Start Claude Code and ask it to call mailbox_status. The result should report connected: true. Use /mcp inside Claude Code to inspect the exposed tools.

Reference: Claude Code MCP documentation.

Cursor

Create or edit the global configuration at ~/.cursor/mcp.json. Global configuration is preferable to .cursor/mcp.json in a project because this server exposes personal email access and should not be committed to another repository.

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

Restart Cursor, open Settings > Tools & MCP, and confirm that proton-safe is enabled and its tools are listed. Then ask the agent to call mailbox_status.

Reference: Cursor MCP documentation.

VS Code

Open the Command Palette and run MCP: Open User Configuration. Add this server to the user-level mcp.json; do not put a personal mail configuration in .vscode/mcp.json in a shared repository.

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

Run MCP: List Servers, start protonSafe if necessary, and inspect its output for startup errors. In an agent chat, ask it to call mailbox_status and confirm that connected is true.

Reference: VS Code MCP configuration.

Draft confirmation

All three clients can call create_confirmed_draft after you explicitly confirm the exact recipients, subject, complete body, and attachments in the conversation. You still review and send the resulting draft yourself in Proton Mail.

No client can send, delete, or move mail: those tools do not exist. A draft therefore stays in your Drafts folder until you send it from Proton Mail yourself.