protonmail-mcp
It lets an agent read and export Proton Mail through local Bridge, with no mail-changing tools in this schema.
List all folders and labels.
List recent emails with folder, limit, unread, date, sender, subject, and cursor filters.
Search emails by full text, folder, sender, recipient, subject, date range, unread status, and attachment presence.
Read a full email, including headers, decoded text/Markdown body, links, attachment metadata, and flags.
Get total and unread counts per folder.
Generate a compact daily digest of unread counts and recent summaries.
Reconstruct email threads chronologically.
List a message’s attachments without saving them.
Save one attachment into the local sandbox without overwriting files.
Export a full message as an .eml file into the local sandbox.
Provides read-only access to a Proton Mail mailbox through a local Proton Bridge instance, with tools to list folders and labels, list recent messages (filtered by unread status, date range, sender, or subject), perform full-text search across headers and body, and read individual messages by Message-ID with decoded text body, attachments, and flags. When the optional draft capability is enabled, it also supports listing, creating, previewing, and two-phase (prepare/commit) management of drafts, including replying, forwarding, updating, and deleting.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@protonmail-mcp show my unread emails from the last 3 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
protonmail-mcp
Let your AI agent work your Proton Mail inbox — without handing it the keys.
An MCP server for Proton Mail, running entirely on your machine through Proton Bridge. Read-only by default, every write previewed before it happens, every limit enforced by the server — not by the prompt.
Quick start · Features · Security · Documentation
Just ask
"What came in overnight that actually needs me?"
"Find the invoice Acme sent last month and save the PDF."
"Draft a polite reply to Alice declining Thursday's meeting."
"Archive every newsletter from this week."
Your agent searches, reads, drafts and tidies your mailbox. You stay in control of anything that changes, sends or deletes mail.
Related MCP server: proton-mcp-server
Why protonmail-mcp
🔒 Safe by default | ✋ You approve every change | 🏠 Nothing leaves your machine |
Starts read-only. Mailboxes are opened | Every edit, move, send and deletion is a prepare → commit pair, bound to the exact preview. | Talks only to Bridge on |
🧱 Limits the model can't talk its way past | 🧾 Audited | 🧪 Heavily tested |
Recipient allowlists, quotas, bulk caps and loop guards live in the server. | Every tool call lands in an append-only local JSONL log. | Adversarial, fuzz and capability-matrix tests, plus CodeQL, semgrep and gitleaks on every push. |
How it works
flowchart LR
A["🤖 AI agent<br/>(Claude, opencode, …)"] -- MCP --> S
subgraph S["protonmail-mcp · your machine"]
direction TB
P["Capability policy"] --> C["Confirmation tokens"] --> L["Audit log"]
end
S -- "IMAP / SMTP<br/>127.0.0.1" --> B["Proton Bridge"]
B -- "end-to-end encrypted" --> PM[("Proton Mail")]Proton has no public mailbox API: Bridge is the supported way in. protonmail-mcp wraps Bridge's local IMAP and SMTP endpoints in a small, auditable set of MCP tools.
Features
Unlock exactly what you need. Each level adds to the previous one, and tools you have not enabled simply do not exist for the agent.
Mode | Your agent can… | Guard rails |
📖 read (default) | List, search and read mail, follow threads, get a daily digest, save attachments and |
|
📝 draft | Write new drafts, reply, reply-all, forward (with original attachments), edit, delete drafts | Writes confined to Drafts; duplicate drafts suppressed |
🗂️ organize | Mark read/unread, flag, move, archive, trash, label — and undo the last move | Bulk cap (50 by default); Drafts protected |
📤 send | Send a draft you have reviewed | Recipient allowlist (self-only by default), hourly/daily quotas, size and loop guards |
🗑️ delete | Permanently erase one message from Trash | Typed confirmation phrase; one message per call; no "empty trash" |
Also included
🔎 Smart reading. Quotes and signatures stripped, HTML rendered to Markdown, link inventory, untrusted-content markers.
⚡ Offline search. Opt-in local SQLite full-text index for instant queries.
🔔 Live updates. Opt-in IMAP IDLE notifications as MCP resource updates.
👥 Multiple accounts. One profile per Proton account, each with its own capability ceiling.
🌐 Runs anywhere. stdio by default; streamable HTTP with mandatory bearer auth; Docker Compose setup for headless hosts.
→ Full list of tools and resources: docs/tools.md
Quick start
You need: a paid Proton Mail plan (required by Bridge), and Proton Bridge installed, running and signed in. Copy the mailbox password shown in the Bridge UI — it is not your Proton password.
1. Install
uvx protonmail-mcp # run without installing (recommended)
pipx install protonmail-mcp # or install it2. Connect your MCP client
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"protonmail": {
"command": "uvx",
"args": ["protonmail-mcp"],
"env": {
"PROTONMAIL_BRIDGE_USERNAME": "you@proton.me",
"PROTONMAIL_BRIDGE_PASSWORD": "your-bridge-mailbox-password"
}
}
}
}Using opencode or another client, or keeping the password out of the config file? See docs/configuration.md.
3. Check the connection
PROTONMAIL_BRIDGE_USERNAME="you@proton.me" PROTONMAIL_BRIDGE_PASSWORD="..." \
uvx protonmail-mcp --checkYou should see your folders and latest messages. That's it — ask your agent about your inbox.
Unlock more
Set PROTONMAIL_MCP_MODE to draft, organize, send or delete, or fine-tune
capabilities, allowlists and quotas in policy.toml. See the
configuration guide
and the annotated policy.example.toml.
Security
Email is attacker-controlled input: a message can try to talk your agent into forwarding your mail, mass-deleting it, or sending spam. protonmail-mcp is built on the assumption that the agent can be manipulated, and puts the hard limits where the model cannot reach them.
Changes are previewed, then committed
New drafts go straight to the Drafts folder. Anything that edits, moves, sends or deletes existing mail takes two calls:
sequenceDiagram
autonumber
participant Agent
participant Server as protonmail-mcp
participant Bridge as Proton Bridge
Agent->>Server: prepare_send_draft(draft)
Server-->>Agent: exact preview + single-use token<br/>(bound to the payload hash, expires in 5 min)
Note over Agent: You review the preview
Agent->>Server: commit_send_draft(token)
Server->>Server: re-check token, payload, allowlist,<br/>quotas, loop guards
Server->>Bridge: SMTP submissionThe token guarantees that what is committed is exactly what was previewed: a replayed, expired or tampered request is rejected. The server-side policy is the hard limit: even an agent that skips the review cannot send outside your allowlist or over your quota.
Guarantees
Fail closed. No configuration means read-only. An invalid policy stops the server from starting.
Least privilege. Disabled capabilities are not registered as tools at all.
Server-side policy. Allowlists, quotas, bulk caps and loop guards are enforced by the server; the agent cannot grant itself privileges.
Sandboxed files. Attachments and exports only touch one directory, with path-traversal protection and filename sanitization. No tool accepts an arbitrary path.
Local only. Bridge on loopback, no telemetry. The test suite blocks non-loopback network access, so none can be added silently.
Untrusted content is labeled. Message bodies are marked as untrusted data for the agent.
Deliberately missing. No raw IMAP/SMTP passthrough, no filter or auto-forward management, no folder creation/deletion, no fetching of links from mail.
Every push runs ruff (bandit rules), strict mypy, adversarial and fuzz tests, gitleaks, zizmor, pip-audit, semgrep and CodeQL. Read the full threat model and security architecture in SECURITY.md, and report vulnerabilities privately through GitHub's Security → Report a vulnerability.
Keep the Bridge password secret. Any local process that knows it can read your mail through Bridge: that is Bridge's trust model. Prefer your client's environment or file-based secret support over inline values.
Documentation
Environment variables, CLI flags, clients, | |
Every tool per capability, resources, index, notifications | |
👥 Profiles | Several Proton accounts |
🌐 HTTP transport · 🐳 Docker | Remote and headless deployments |
🛠️ Development | Tests and releases |
🧭 Alternatives · 🗺️ Roadmap | Other servers, what's next |
MIT licensed · Unofficial: not affiliated with, endorsed by, or supported by Proton AG. "Proton Mail" and "Proton Bridge" are trademarks of Proton AG.
Available Tools
10 toolsdaily_digestARead-only
Compact digest of a folder: unread count plus recent message summaries (subjects and senders only, no bodies).
Args: folder: Folder to summarize. days: Window in days (default 1). limit: Maximum messages in the digest (1-100).
Inputs: days, limit, folder. Returns: folder, unread, messages, since_days, +1 more
export_emailA
Export a full message as .eml into the local sandbox directory.
Args: message_id: Message-ID of the message. folder: Folder containing the message. filename: Optional target filename; defaults to the Message-ID plus .eml.
Inputs: message_id (required), folder, filename. Returns: path, filename, size_bytes, content_type
get_statusARead-only
Counts of total and unread messages per folder, without fetching messages.
Args: folder: A single folder name, or omit to get every selectable folder.
Inputs: folder. Returns: result
get_threadARead-only
Reconstruct a conversation around a message using References/In-Reply-To, searching All Mail. Returns messages in chronological order.
Args: message_id: Message-ID of any message in the thread. folder: Folder containing that message (used as a fallback if All Mail is absent). limit: Maximum messages in the thread (1-100).
Inputs: message_id (required), limit, folder. Returns: result
list_attachmentsARead-only
List a message's attachments (names, content types, sizes) without saving anything to disk.
Args: message_id: Message-ID of the message. folder: Folder containing the message.
Inputs: message_id (required), folder. Returns: result
list_emailsARead-only
List the most recent messages of a folder, newest first.
Args: folder: Folder or label name, as returned by list_folders. limit: Maximum number of messages to return (1-100). unread_only: Only return unread messages when true. since_days: Only return messages from the last N days when set. sender: Only return messages whose From header contains this text. subject: Only return messages whose Subject header contains this text. before: Cursor from a previous page's next_cursor to continue listing.
Inputs: limit, before, folder, sender, +3 more. Returns: folder, messages, next_cursor
list_foldersARead-only
List every folder and label of the mailbox. Use this first when you do not know where a message lives; the returned names are valid values for other tools.
Inputs: no named parameters. Returns: result
read_emailARead-only
Read one full message, identified by the Message-ID returned by list_emails or search_emails. Returns headers, decoded text body, attachment names, and flags.
Args: message_id: Full Message-ID header value, including angle brackets. folder: Folder the message is in. max_chars: Maximum body characters to return; longer bodies are truncated.
Inputs: message_id (required), folder, max_chars. Returns: cc, uid, date, links, +17 more
save_attachmentA
Save one attachment into the local sandbox directory. Files are never overwritten and never leave the sandbox.
Args: message_id: Message-ID of the message. folder: Folder containing the message. filename: Exact attachment filename; omit when the message has exactly one. index: Attachment position (0-based) when filenames are ambiguous.
Inputs: message_id (required), index, folder, filename. Returns: path, filename, size_bytes, content_type
search_emailsARead-only
Search messages, newest first. All filters combine with AND.
Args: query: Full-text across headers and body; empty matches everything. folder: Folder or label name to search in, as returned by list_folders. limit: Maximum number of messages to return (1-100). sender: Substring match on the From header. recipient: Substring match on the To header. subject: Substring match on the Subject header. since_days: Only messages received in the last N days. before_days: Only messages received before N days ago. unread_only: Only unread messages when true. has_attachment: Only messages carrying an attachment. IMAP cannot search on this, so up to 200 newest candidates are checked with BODYSTRUCTURE; the result reports how many were scanned and whether the set was truncated.
Inputs: limit, query, folder, sender, +6 more. Returns: scanned, messages, truncated
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Tools mostly target distinct actions or resources, but list_emails and search_emails overlap in filtering, and get_status and daily_digest both report unread counts. An agent can infer the difference from descriptions, but there is mild potential for misselection.
Names mostly follow a verb_noun pattern: list_folders, list_emails, search_emails, read_email, get_status, get_thread, list_attachments, save_attachment, export_email. daily_digest is the only noun-phrase outlier, a minor inconsistency.
10 tools is well-scoped for an email access server; each tool covers a distinct capability without obvious redundancy. The count is neither too thin nor too heavy.
The surface covers read-oriented mailbox operations well: folders, listing, search, read, threads, attachments, and export. However, it lacks send/compose, delete, move, and label/mark-read operations, which are notable gaps for a full email lifecycle.
Maintenance
Related MCP Connectors
Bring Gmail, Outlook, iCloud Mail, Yahoo Mail, Fastmail and other IMAP mailboxes together. Search connected email, including semantic search; cached or indexed results may be incomplete or stale. Read messages and attachments, create drafts, send or reply when requested, and manage rules for new mail. Separate permissions control reading, attachments, drafts, sending and mailbox changes.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Private, EU-hosted email for AI agents over JMAP: read, search, reply, draft, organize, send.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to read and search Proton Mail inbox through Proton Mail Bridge, providing tools to list mailboxes, list messages, search messages, and fetch full message bodies. Read-only, with secure certificate pinning.444 npm2MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Proton Mail via MCP, enabling AI agents to list accounts/folders, search messages, and read emails using Proton Mail Bridge's local IMAP server.MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read, organize, and send Proton Mail through the local Proton Bridge, with careful gating for sending and attachment access.252Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with a Proton Mail mailbox through Proton Bridge, supporting listing, searching, reading, sending, and organizing emails.-