Proton Mail MCP Server

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.):

{
  "mcpServers": {
    "protonmail": {
      "command": "npx",
      "args": ["-y", "proton-mail-mcp"],
      "env": {
        "PROTONMAIL_USERNAME": "your-email@protonmail.com",
        "PROTONMAIL_PASSWORD": "your-smtp-password"
      }
    }
  }
}

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:

git clone https://github.com/sethbang/proton-mail-mcp.git
cd proton-mail-mcp
npm install
npm run build

Then use this MCP config instead:

{
  "mcpServers": {
    "protonmail": {
      "command": "node",
      "args": ["/absolute/path/to/proton-mail-mcp/build/index.js"],
      "env": {
        "PROTONMAIL_USERNAME": "your-email@protonmail.com",
        "PROTONMAIL_PASSWORD": "your-smtp-password"
      }
    }
  }
}

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 <script>, event handlers, inline style attributes, and remote <img> 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.

⚠️ Display-name spoofing partially defended. As of v1.0.0, fromName rejects values containing @ by default — without this guard, a fromName like "Anthropic Security <security@anthropic.com>" reaches the wire as Anthropic Security security@anthropic.com after angle-bracket sanitization, which mail clients render as a forged sender. Pass allowAddressLikeFromName: true to override for legitimate product names. SMTP itself still prevents address-level spoofing (the envelope From: is bound to your authenticated identity), and arbitrary display names without @ are still allowed (e.g. "CEO of Acme") — treat fromName like any other user-controllable string.

All send/reply/forward/save_draft tools accept an alternative markdownBody parameter (rendered to HTML via marked) — mutually exclusive with body+isHtml. sanitizeHtml applies after Markdown rendering.

🛡️ Outbound preview + self-only lock. send_email, reply_email, reply_all_email, and forward_email accept dryRun: true — it runs all validation and resolves the complete recipient set (To/CC/BCC, including the reply-all fan-out) and returns it without sending, leading with an [outbound:*] token and an explicit list of any external (non-self) recipients. Use it to confirm exactly who would receive the mail before a live call. For throwaway/QA accounts, set RESTRICT_OUTBOUND_TO_SELF=true (see Environment variables) to refuse any live send to a non-self recipient — preventing an agent from fanning real mail out to external addresses embedded in seed data. (Preview is caller-opt-in; the env lock is enforced server-side with no per-call override.)

send_email

Send an email using Proton Mail SMTP.