Proton Safe MCP

A client-agnostic FastMCP server for Proton Mail through the official Proton Mail Bridge. It can read and search mail and create drafts with attachments. It deliberately cannot send email — you review every draft in Proton Mail and press Send yourself.

The server runs locally over STDIO for any MCP-compatible client (Claude Desktop, Claude Code, or anything else that speaks MCP). Received PDF, TXT, and CSV attachments can be inspected through bounded text extraction without exposing their raw bytes. Outgoing attachments are uploaded as bounded base64 chunks, so the server never receives or reads a client filesystem path.

Read the full documentation for setup, configuration, tool inputs, security boundaries, and troubleshooting.

Why "safe"?

Email is attacker-controlled input. Any sender can put adversarial instructions in a message body, and an AI agent that reads mail and holds write-capable tools is one prompt injection away from doing something you did not ask for. This project limits the blast radius by construction:

• No send. There is no SMTP client and no send_message tool in the codebase — a test asserts it.
• No delete, no move, and no raw received-attachment download tool.
• Human in the loop. Draft creation requires explicit confirmation of the exact content in the conversation, and Proton Mail still requires manual review and sending.
• No filesystem access for clients. Attachment bytes are streamed in chunks with declared size and SHA-256 verification; paths are rejected.
• Loopback only. STDIO transport, no listening socket, and the Bridge host is hard-coded to 127.0.0.1.

These controls reduce risk but do not make email trusted. Never expose unrelated write-capable tools in the same unattended agent workflow.

Architecture

Security properties

• STDIO only: the server opens no listening network socket.
• Proton Bridge host is hard-coded to 127.0.0.1 (PROTON_BRIDGE_HOST is intentionally unsupported).
• No SMTP client, send tool, delete tool, move tool, or raw received-attachment download tool.
• Message and attachment reads use BODY.PEEK; attachment inspection returns bounded extracted text, metadata, and a SHA-256 digest, never raw bytes or files.
• Attachment input is chunked base64 with declared size and SHA-256 verification.
• Only PDF, DOCX, XLSX, PPTX, TXT, CSV, PNG, and JPEG uploads are accepted.
• Attachment tokens are random, short-lived, single-use, and reverified before draft creation.
• Draft creation requires an explicit client assertion that the user confirmed the exact recipients, subject, body, and attachments in the conversation.
• The Bridge-generated IMAP password is stored in the operating-system keyring.
• Draft bodies are stored as plain text plus a server-generated HTML alternative that HTML-escapes the confirmed body, so quoted markup can never be rendered. Nothing is ever appended to a body server-side, including a reply quote.
• Replying adds threading headers only. Recipients are never derived from the message being replied to, its Message-ID is reverified at the IMAP write, and both identifiers are validated so neither can continue into a header of its own.
• Recipient, subject, and folder inputs are validated against header/criteria injection.
• State files are private to the Unix account (0700 directories, 0600 files, O_NOFOLLOW).

Requirements

• Linux with the official Proton Mail Bridge installed, signed in, and running (developed and tested on Ubuntu).
• A Proton plan that supports Bridge.
• Python 3.11 or newer.
• uv.
• A working Secret Service keyring (gnome-keyring or compatible).

Installation

Install the reviewed release from PyPI with uv:

uv tool install proton-safe-mcp==2.0.3

For development from source instead:

git clone https://github.com/fbossiere/proton-safe-mcp.git
cd proton-safe-mcp
uv sync --extra dev

Set the Proton address and Bridge IMAP port in the MCP process environment. No credential is ever set here:

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

To draft as another Proton address of the same account, add the optional sender allowlist in that same environment, as comma-separated bare addresses:

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

Store the Bridge-generated IMAP password (shown in the Bridge UI), not your Proton account password:

proton-safe-mcp setup

The value shown by Bridge is installation-specific and works only against the local Bridge.

Register with an MCP client

Configure a local STDIO server with these logical fields. Use command -v proton-safe-mcp to obtain the absolute command path when your client does not inherit your shell PATH:

{
  "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 goes in the same env block when a draft may use more than one From address. See Sender addresses.

Do not put PROTON_BRIDGE_PASSWORD in the client configuration. The server reads it from the OS keyring established by setup.

Copy-paste instructions are available for Claude Code, Cursor, and VS Code. AI coding agents can follow the safety-constrained llms-install.md guide.

Verify the complete local setup without printing credentials, addresses, or mailbox data:

proton-safe-mcp doctor

OpenAI plugin

The repository includes a private, local-first Proton Safe plugin for ChatGPT and Codex. It packages safety-focused mail review and draft workflows with the same restricted MCP server:

• ChatGPT desktop and Codex can launch the bundled STDIO configuration directly on the Bridge machine, with no tunnel or dedicated server;
• direct MCP registration remains available when the packaged workflow skills are not needed;
• ChatGPT web or a client on another machine can optionally reach the Bridge host through OpenAI Secure MCP Tunnel without an inbound port;
• a remote deployment still keeps proton-safe-mcp and Proton Mail Bridge together, with IMAP fixed to 127.0.0.1.

See the OpenAI plugin guide for local ChatGPT desktop/Codex installation, direct MCP registration, and the optional remote tunnel.

Plugin installed but no Proton tools? The bundled MCP configuration forwards PROTON_BRIDGE_USER and PROTON_IMAP_PORT from the environment that started Codex; it does not define their values. On Ubuntu, a correct ~/.config/environment.d/*.conf file can still require a user-manager reload, while GNOME and already-running terminals can keep their earlier environment. If a menu relaunch still has no tools, start ChatGPT once from a terminal that has loaded the file. That terminal launch is a diagnostic, not a requirement for every start; the troubleshooting guide also provides a persistent per-user menu launcher. Follow the privacy-safe Ubuntu recovery procedure or the FAQ before reinstalling anything.

Help test the onboarding. Linux and Proton Mail Bridge users can run the 10-minute external test and submit privacy-safe installation feedback.

Available MCP tools