proton-mcp

A self-hosted Model Context Protocol (MCP) server for Proton Mail, designed to run next to Proton Mail Bridge and expose a small, auditable set of mailbox tools to MCP clients.

Status: early development. Bounded metadata tools, controlled explicit-id writes, and the reviewable cleanup workflow are implemented. Live deployment status is tracked separately from this source repository.

Goals

• Run continuously on a NAS or home server with Docker Compose.

• Keep Proton Mail Bridge isolated from the LAN and internet.

• Talk to Bridge over local IMAP/SMTP rather than handling Proton encryption directly.

• Expose narrow MCP tools instead of generic shell or filesystem access.

• Make mailbox cleanup efficient by returning metadata first and full message bodies only on demand.

• Keep mutations explicit, bounded, reviewable, and reversible where IMAP can prove an exact reversal.

Related MCP server: proton-mail-mcp

Mailbox tools

• list_folders

• mailbox_stats

• top_senders

• mailbox_inventory

• cleanup_candidates

• mailbox_analysis

• newsletter_review

• search_mail

• get_message

• extract_receipt

• receipt_candidates

• create_bulk_cleanup_run

• bulk_cleanup_history

• bulk_cleanup_progress

• approve_bulk_cleanup_run

• apply_bulk_cleanup_run

Controlled management tools are also available for bounded, explicit-id operations: mark_read, mark_unread, archive_messages, move_messages, copy_messages, and trash_messages. They support dryRun; permanent deletion is not exposed.

For reviewed batches, use create_cleanup_plan followed by apply_cleanup_plan. Plans expire after 15 minutes and require a one-time confirmation token. cleanup_history and undo_cleanup_operation are available only for completed operations; undo is offered only when Bridge returns exact destination UID mappings.

Manual automation rules are available through create_automation_rule, prepare_automation_run, and automation_history. Rules are disabled by default and prepare a reviewable cleanup plan rather than changing mail directly. Optional scheduled reviews only record bounded candidates for later review; they do not create confirmation tokens or mutate mail.

Disabled rules can be changed with update_automation_rule or removed with delete_automation_rule, which also cancels any unused plan from that rule. Review-only bulk cleanup manifests can be created with create_bulk_cleanup_run and inspected with bulk_cleanup_history. After review, approve_bulk_cleanup_run authorizes one run and apply_bulk_cleanup_run processes it through internal 50-message plans while recording progress and operation history. Use maxChunks to bound each request and continue a paused run with the same confirmation token. Permanent deletion remains unavailable; an unexpected interruption leaves the run for manual review rather than retrying an uncertain chunk. Bulk reviews support protected sender, domain, and subject-term exclusions. newsletter_review groups standard List-Unsubscribe headers by sender and reports mailto/HTTPS options for review; it never sends unsubscribe requests.

See docs/SPEC.md for the tool contract and ARCHITECTURE.md for the deployment model.

Transports

The container defaults to authenticated Streamable HTTP:

POST /mcp
GET  /healthz

Runtime configuration:

MCP_HOST=0.0.0.0
MCP_PORT=3000
MCP_AUTH_TOKEN_FILE=/run/secrets/mcp_auth_token
MCP_ALLOWED_HOSTS=localhost,127.0.0.1,[::1]
MCP_ALLOWED_ORIGINS=

MCP_AUTH_TOKEN_FILE must contain a bearer token of at least 32 characters. Keep it in a mounted secret file rather than committing it or putting it in Compose environment values.

MCP_ALLOWED_HOSTS is a comma-separated hostname allowlist. If a reverse proxy preserves an external hostname, add that hostname explicitly. Browser requests carrying an Origin header are rejected unless that exact origin is present in MCP_ALLOWED_ORIGINS; normal non-browser MCP clients usually send no Origin header.

For local child-process clients, stdio remains available:

node dist/index.js stdio

For development:

npm run dev       # stdio
npm run dev:http  # Streamable HTTP

Deployment model

MCP client
    |
    | authenticated Streamable HTTP
    v
proton-mcp container
    |
    | localhost IMAP
    v
proton-bridge container
    |
    v
Proton Mail

The intended Docker Compose deployment gives proton-mcp and proton-bridge a shared network namespace so Bridge can remain bound to loopback. IMAP/SMTP ports must not be published to the LAN. The MCP HTTP port should be published only to the intended trusted path, such as host loopback for a local reverse proxy.

The live Synology deployment is maintained separately in nmousouros/nas-infrastructure, under stacks/proton-mail/. When that repository is available in the same workspace, its root STATE.md is the source of truth for changing runtime facts such as deployment status, live ports, Bridge sync state, and which tools have been validated against the real mailbox. Do not duplicate those changing facts here.

The Bridge image itself is maintained in purplehat93/proton-bridge-docker.

Development principles

• No Proton account password in the repository, image, logs, or normal environment variables.

• No arbitrary shell MCP tool.

• No permanent-delete MCP tool.

• Prefer deterministic mailbox processing to sending large volumes of email content to an LLM.

• Keep validation simple: future agents should be able to run one command (make check) before finishing work.

• A source change in this repository is not permission to deploy or restart the live NAS stack.

Documentation

• AGENTS.md — concise instructions for coding agents.

• ARCHITECTURE.md — system boundaries and decisions.

• SECURITY.md — security invariants.

• docs/SPEC.md — MCP tool contract.

• docs/DEVELOPMENT.md — local development workflow.

• docs/OPERATIONS.md — Synology / Docker operations.

• docs/ROADMAP.md — implemented work and pending ideas.

License

MIT. See LICENSE.