fbossiere/proton-safe-mcp

**Website & download · En français**
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.
- Proton Bridge does not preserve reply threading in saved drafts. Reply targets are refused
unless the user explicitly accepts a possibly separate draft. Accepted replies submit 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 one account. On Linux: 0700 directories, 0600 files and
O_NOFOLLOW. On Windows: a protected DACL granting only the owning user and the system
accounts, with reparse points refused in place of 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–3.14 (tested in CI) for the command-line installation; bundled in the desktop installer.