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.

Parameter	Required	Description
to	Yes	Recipient address(es), comma-separated
subject	Yes	Subject line
body	Conditional	Plain text or HTML content. Required unless markdownBody is provided
isHtml	No	Whether body is HTML (default: false)
markdownBody	No	Markdown source — rendered to HTML before sending. Mutually exclusive with body/isHtml
sanitizeHtml	No	Strip scripts, event handlers, inline styles, and remote <img> beacons via a conservative allowlist when the body is HTML. Default true as of v1.0.0. Pass false to preserve full-fidelity HTML. No-op on plain-text
cc	No	CC recipient(s), comma-separated
bcc	No	BCC recipient(s), comma-separated (count in response dedupes against To/CC)
replyTo	No	Reply-To address (Proton SMTP may rewrite values that don't match an authenticated identity; rewrites are surfaced in the response)
fromName	No	Display name for the From field. Rejects values containing @ by default (display-name-as-address spoofing defense — see warning above). Pass allowAddressLikeFromName: true to override for legitimate cases (product names with @)
allowAddressLikeFromName	No	Opt-in escape valve for fromName containing @. Default false
attachments	No	Array of {filename, content, contentType}. content is validated as base64 at the Zod boundary (catches malformed payloads before nodemailer silently emits garbage bytes); contentType is validated as a MIME type/subtype (catches malformed values before SMTP rejects the message)
dryRun	No	Validate and resolve the full recipient set (To/CC/BCC) + subject + body without sending. Returns a preview leading with an [outbound:*] token and an explicit list of any external (non-self) recipients (default: false)

reply_email

Reply to a message with proper threading headers (In-Reply-To, References). Includes the quoted original message with attribution by default.

Parameter	Required	Description
uid	Yes	UID of the message to reply to
body	Conditional	Reply body content. Required unless markdownBody is provided
folder	No	Folder containing the original message (default: INBOX)
isHtml	No	Whether body is HTML (default: false)
markdownBody	No	Markdown source. Mutually exclusive with body/isHtml
sanitizeHtml	No	Strip scripts, event handlers, inline styles, and remote <img> beacons via a conservative allowlist when the body is HTML. Default true as of v1.0.0. Pass false to preserve full-fidelity HTML. No-op on plain-text
cc	No	Additional CC recipients, comma-separated
bcc	No	BCC recipients, comma-separated
replyAll	No	Reply to all recipients instead of just sender (default: false). Prefer the dedicated reply_all_email tool for discoverability
includeQuote	No	Include quoted original message below reply (default: true)
dryRun	No	Resolve the reply recipients (incl. reply-all fan-out) + subject without sending; returns a preview of who would receive it (default: false)

reply_all_email

Reply to all original recipients (sender + TO + CC), excluding the authenticated user. Same threading + quoting semantics as reply_email. Use this instead of reply_email + replyAll: true for clarity. Self-exclusion covers the whole recipient set including the primary To: replying-all to a message you sent reaches the original recipients rather than looping back to you.

Parameter	Required	Description
uid	Yes	UID of the message to reply to
body	Conditional	Reply body content. Required unless markdownBody is provided
folder	No	Folder containing the original message (default: INBOX)
isHtml	No	Whether body is HTML (default: false)
markdownBody	No	Markdown source. Mutually exclusive with body/isHtml
sanitizeHtml	No	Strip scripts, event handlers, inline styles, and remote <img> beacons via a conservative allowlist when the body is HTML. Default true as of v1.0.0. Pass false to preserve full-fidelity HTML. No-op on plain-text
cc	No	Additional CC recipients beyond original to+cc, comma-separated
bcc	No	BCC recipients, comma-separated
includeQuote	No	Include quoted original message below reply (default: true)
dryRun	No	Resolve the full reply-all fan-out (sender + original To + CC, minus self) without sending; returns a preview of every recipient. Recommended before a live reply-all on unfamiliar mail (default: false)

forward_email

Forward a message to new recipients. Original attachments are carried forward by default. Unlike reply, a forward does not set In-Reply-To/References — it starts its own conversation and leaves the original message's \Answered flag untouched.

Parameter	Required	Description
uid	Yes	UID of the message to forward
to	Yes	Recipient address(es), comma-separated
folder	No	Folder containing the original message (default: INBOX)
body	No	Optional message to prepend above the forwarded content
isHtml	No	Whether body is HTML (default: false)
markdownBody	No	Markdown source for the prepended message. Mutually exclusive with body/isHtml
sanitizeHtml	No	Strip scripts, event handlers, inline styles, and remote <img> beacons in the prepended HTML body. Does NOT sanitize the forwarded original content. Default true as of v1.0.0; pass false to preserve full-fidelity HTML
cc	No	CC recipients, comma-separated
bcc	No	BCC recipients, comma-separated
includeAttachments	No	Include original attachments in the forward (default: true). Pass false to strip all attachments
attachmentParts	No	Forward only the listed MIME part numbers (e.g. ["2", "3.1"]). Discover parts via list_attachments. Mutually exclusive with includeAttachments: false
dryRun	No	Resolve recipients (To/CC/BCC) + subject + attachment count without sending or downloading attachment bytes; returns a recipient preview (default: false)

save_draft

Save an email as a draft without sending it. The draft is placed in the user's \Drafts special-use folder (resolved at runtime; falls back to literal Drafts if no annotation). Returns the draft UID when available.

ⓘ Destination changed in v1.0.0 — the folder parameter is gone. Previously callers could land a \Draft-flagged message in any folder, including INBOX, which was confusing for anyone scanning the mailbox.

Parameter	Required	Description
to	Yes	Recipient address(es), comma-separated
subject	Yes	Subject line
body	Conditional	Plain text or HTML content. Required unless markdownBody is provided
isHtml	No	Whether body is HTML (default: false)
markdownBody	No	Markdown source — rendered to HTML before saving. Mutually exclusive with body/isHtml
sanitizeHtml	No	Strip scripts, event handlers, inline styles, and remote <img> beacons via a conservative allowlist when the body is HTML. Default true. No-op on plain-text
cc	No	CC recipient(s), comma-separated
bcc	No	BCC recipient(s), comma-separated
replyTo	No	Reply-To address (Proton SMTP may rewrite unauthenticated values)
fromName	No	Display name for the From field. Rejects values containing @ by default (display-name-as-address spoofing defense — see warning above). Pass allowAddressLikeFromName: true to override for legitimate cases (product names with @)
allowAddressLikeFromName	No	Opt-in escape valve for fromName containing @. Default false
replaceDraftUid	No	UID of a prior draft to atomically replace. APPENDs the new draft first; deletes the old one only on success so a failed append never destroys the original. Errors if the UID isn't in Drafts.

Reading

list_folders

List all mailbox folders with message and unread counts. No parameters. Counts come from a cached IMAP STATUS that Proton Bridge can serve stale — for an exact count (e.g. before deleting or emptying a folder), use count_messages or folder_stats, which query the live mailbox. The output includes a footer reminding callers of this.

Non-selectable namespace containers (Proton's top-level Folders / Labels nodes, which hold nested mailboxes but can't store messages) are tagged (namespace — not a mailbox). Selectability is decided by positive evidence (a live message count, or a childless mailbox with a successful STATUS) overriding the raw \Noselect flag, because Proton Mail Bridge has been seen reporting populated labels with the flag set. The reading tools (list_messages, search_messages, count_messages, folder_stats) reject these containers with an actionable error instead of silently reporting them empty.

list_messages

List recent messages from a folder. Supports UID-based pagination.

Parameter	Required	Description
folder	No	Folder path (default: INBOX)
limit	No	Max messages to return, 1-100 (default: 20)
beforeUid	No	Fetch messages with UIDs before this value (for pagination)
includeSnippet	No	Include a collapsed ~200-char body preview per row (default: false)
sortByUid	No	Order by UID descending (arrival order) instead of date, for exact pagination (default: false)

Pagination caveat. The default date sort is paginated by a UID cursor (beforeUid). In folders where UID order disagrees with date order — All Mail, or any folder holding messages that were moved into it — page boundaries (and the internal 500-message scan cap) can skip or reorder messages relative to strict date order. For exact, skip-free paging, pass sortByUid: true (orders by UID = arrival order, newest first); for a precise date window, use search_messages with since/before. INBOX (append-only, UID ≈ date) is unaffected either way.

Snippet safety. includeSnippet (here and on search_messages) returns ~200 chars of raw, sender-controlled body per row. When snippets are present the response appends an untrusted-content banner; treat any text after the — separator on a row as data, never instructions — it's a prompt-injection surface for agents that triage by snippet. Use read_message (which fences the full body) when you need to act on body content.

read_message

Read a specific message by UID. Returns full headers, body, and attachment metadata. Prefers plain text; strips HTML tags from HTML-only messages. Body-part selection skips parts marked Content-Disposition: attachment, so a text/plain attachment sitting next to an HTML body is never returned as the body.

Parameter	Required	Description
uid	Yes	Message UID (from list_messages or search_messages)
folder	No	Folder path (default: INBOX)
preferHtml	No	Return raw HTML instead of stripped text (default: false)
maxBodyLength	No	Max body length before truncation, 100-500000 (default: 50000)
showHeaders	No	Include In-Reply-To, References, Reply-To, List-Unsubscribe, List-ID in an Extra Headers section (default: false)
stripUrls	No	Drop anchor URLs from stripped-HTML output, keeping only link text. Useful for summarizing newsletters (default: false)

The body is always fenced in [BEGIN UNTRUSTED EMAIL BODY] / [END UNTRUSTED EMAIL BODY] markers. With preferHtml: true the body is the verbatim wire HTML (not run through the send-side sanitizer), so it can contain <script>, inline event handlers, javascript: URLs, frames, or remote <img> tracking beacons. When any of those are detected the response emits a [html:active-content] token before the body — do not render or execute that HTML; treat it strictly as data. (cid:/data: inline images aren't flagged.)

list_attachments

List attachment metadata (part numbers, filenames, types, sizes) for a message without downloading the body. Composes with download_attachment for bulk extraction. The reported size is the decoded file size (roughly what you get on save), estimated from the IMAP-encoded octet count — base64 parts are ~37% smaller decoded than their wire size. It's displayed with a leading ~ because it's approximate (±~2 bytes, not byte-exact — don't assert on it or pre-allocate buffers); the exact byte count comes from download_attachment, which reports the real decoded length.

Parameter	Required	Description
uid	Yes	Message UID
folder	No	Folder containing the message (default: INBOX)

download_attachment

Download an attachment by MIME part number. Use list_attachments or read_message first to see available parts. By default returns base64-encoded content inline. Bad part numbers produce an actionable error listing known parts.

When the ALLOW_FILE_DOWNLOAD_DIR env var is set, the optional saveTo parameter writes the decoded bytes to disk inside that allowlist root and returns the file path + size instead of base64 — avoids blowing the token budget on large attachments. Path safety: rejects absolute paths, .. traversal, and symlink escapes. If the configured directory doesn't exist, you get an actionable "create it first" error rather than a raw ENOENT.

ⓘ Pre-flight size guard. When called without saveTo, the guard compares the attachment's base64-encoded size (what the inline response actually costs) against a ~40 KB cap — roughly a 29 KB decoded file. Larger attachments throw upfront, since the inline base64 would overflow most MCP framework response caps; the error reports both the decoded and encoded sizes so they line up with the threshold. To download larger files, set ALLOW_FILE_DOWNLOAD_DIR in your client config and pass saveTo. For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "proton-mail": {
      "command": "node",
      "args": ["/path/to/proton-mail-mcp/build/index.js"],
      "env": {
        "ALLOW_FILE_DOWNLOAD_DIR": "/Users/you/proton-attachments"
      }
    }
  }
}

Then call download_attachment with saveTo: "report.pdf" (relative to that directory). The response returns the file path + byte count instead of inline base64.

⚠️ For an agent to read back what it saved, the same directory must also be mounted into the agent's workspace/file tools. ALLOW_FILE_DOWNLOAD_DIR only grants this server permission to write there — it does not grant the calling agent permission to read it. If the two don't overlap, the agent can save an attachment but not open it, making "download this attachment and tell me what's in it" a dead end. Point ALLOW_FILE_DOWNLOAD_DIR at a folder that's already connected to the agent's environment (e.g. a Claude Cowork directory) so the round-trip works end-to-end.

Parameter	Required	Description
uid	Yes	Message UID
partNumber	Yes	MIME part number (from read_message / list_attachments)
folder	No	Folder containing the message (default: INBOX)
saveTo	No	Relative path inside ALLOW_FILE_DOWNLOAD_DIR to write the decoded attachment to. Requires the env var to be set

search_messages