Skip to main content
Glama
protonmail-mcp

protonmail-mcp

by mhbxyz

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.

PyPI Python License: MIT CI CodeQL OpenSSF Scorecard

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 READONLY; not even the unread flag moves.

Every edit, move, send and deletion is a prepare → commit pair, bound to the exact preview.

Talks only to Bridge on 127.0.0.1. No telemetry, no third party, no cloud.

🧱 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 .eml exports

READONLY mailboxes; files only in a local sandbox

📝 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 it

2. 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 --check

You 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 submission

The 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

⚙️ Configuration

Environment variables, CLI flags, clients, policy.toml

🧰 Tools and resources

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 tools
daily_digestA
Read-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_statusA
Read-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_threadA
Read-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_attachmentsA
Read-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_emailsA
Read-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_foldersA
Read-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_emailA
Read-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_emailsA
Read-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

    A3.9/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      4
      44 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read, organize, and send Proton Mail through the local Proton Bridge, with careful gating for sending and attachment access.
      25
      2
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with a Proton Mail mailbox through Proton Bridge, supporting listing, searching, reading, sending, and organizing emails.
      -