sethbang/proton-mail-mcp

A Model Context Protocol (MCP) server that gives AI assistants full access to your Proton Mail account -- send, read, search, and organize email over SMTP and IMAP.
> ⚠️ **Unofficial — not affiliated with Proton.** This is an independent, community-built project. It is **not** developed, endorsed, sponsored, or supported by Proton AG. "Proton", "Proton Mail", and "Proton Mail Bridge" are trademarks of Proton AG, used here only to describe interoperability. It talks to Proton Mail over the standard SMTP submission endpoint and the locally-run Proton Mail Bridge; no Proton private API is used. Use at your own risk.
Demo
Features
- **Send, reply, and forward** email via Proton Mail SMTP with threading headers; dedicated reply_all_email tool
- **Markdown bodies** -- pass markdownBody to send_email / reply_email / reply_all_email / forward_email; rendered to HTML with a plain-text fallback
- **Read email** via IMAP through Proton Mail Bridge
- **Attachments** -- send files (base64), download to memory or to disk (saveTo + ALLOW_FILE_DOWNLOAD_DIR), forward a subset by part number
- **Search** messages by sender, recipient, subject, body, date, flags, size, List-ID, attachment presence, attachment name (substring), and attachment MIME type
- **Organize** -- move, delete, and flag/unflag messages individually or in bulk; bulk-update labels too
- **Bulk operations** -- bulk_move, bulk_delete, bulk_update_flags, bulk_update_labels with dryRun preview and XOR uid/match input
- **Folder & label management** -- create_folder, create_label, rename_folder, delete_folder (non-destructive on Proton); empty_folder (opt-in via ALLOW_EMPTY_FOLDER=true; not recommended)
- **Labeling** -- update_message_labels adds and removes Proton labels on a message (additive — message stays in its source folder)
- **Aggregations** -- count_messages, folder_stats, top_senders (with excludeSelf + per-row direction) for inbox analytics
- **Thread mutations** -- move_thread, delete_thread, flag_thread with optional cross-folder walk; get_thread dedupes by Message-ID across mailbox copies
- **Snippets** -- optional includeSnippet on list_messages and search_messages for at-a-glance previews
- **List folders** with message and unread counts
- **Honest accounting** -- post-STORE FETCH verify on flags/labels surfaces silently-dropped operations as notApplied; sent-copy lookup retries SEARCH to defeat Proton's index lag; Reply-To rewrites are surfaced in the send response
- **Safety first** -- delete moves to Trash by default (via special-use resolver), read-only mode via READONLY=true, dryRun on all bulk ops, MCP tool annotations for client-side confirmation prompts, path-traversal defense on filesystem-touching tools
- **Security hardened** -- input validation, credential sanitization, rate limiting, attachment size limits
- Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)
Prerequisites
- Node.js v24+
- A Proton Mail account with an SMTP password (how to get one)
- Proton Mail Bridge running locally (required for IMAP/read tools)
Quick Start
Add to your MCP client
Add the following to your client's MCP server configuration (Claude Desktop, Claude Code, Cursor, etc.):
That's it — npx will download and run the server automatically. See Configuration for all available environment variables.
Install from source
If you prefer to run from a local clone:
Then use this MCP config instead:
Tools
Sending
All send tools return the Message-ID of the sent message in their response, which can be used to locate the message via IMAP search. All four send tools (send_email, reply_email, reply_all_email, forward_email) perform a best-effort lookup of the sent copy UID in the resolved \Sent folder (retried across ~30s to defeat Proton's indexing lag) and lead the response with a machine-parseable token prefix — [sent-copy:verified] or [sent-copy:unverified], plus [reply-to:preserved|rewritten|stripped|unverified] when replyTo was requested. Agents can grep these tokens instead of text-matching prose. When the Sent-copy lookup converges, the response also includes a Sent copy UID: N in Sent clause; when it doesn't, the leading verb switches from "X sent successfully (Sent-copy verified)" to "X send accepted by SMTP (Sent-copy unverified within the lookup window)" — the message did go out, but per-delivery verification couldn't be completed within the budget.
> 🛡️ **HTML sanitization defaults to ON** (since v1.0.0). Send / reply / forward / save_draft tools strip , event handlers, inline style attributes, and remote beacons via a conservative allowlist before delivery. Pass sanitizeHtml: false to preserve full-fidelity HTML for trusted-content workflows. The success response notes when sanitization ran.