proton-mail-bridge-mcp: Instructions file for Claude Code

proton-mail-bridge-mcp

What this is

A small, free, open-source MCP server that gives any MCP client (Claude Code, Claude Desktop, Cursor, Cline, …) access to a user's ProtonMail — search, read, draft, send, organise. It's a standalone project, not part of BrainBoxx, but it's a deliberate gateway to it (see Positioning).

Scaffolded 2026-08-17 as a sibling folder to brainboxx/. Born out of a BrainBoxx conversation: "CLI having Gmail is great, can we do Proton?" → the clean answer is a local MCP server, and it doesn't belong inside BrainBoxx (BrainBoxx is a transport/control layer; an MCP server is an agent capability — orthogonal). It composes for free: pair the machine with BrainBoxx and you drive your Proton from your phone with zero code shared between the two.

The hard dependency — read this first

There is no public ProtonMail API (Proton is end-to-end encrypted by design). The only sanctioned way in is Proton Bridge, which Proton ships to expose a local IMAP + SMTP server on 127.0.0.1. So:

• This server talks IMAP/SMTP to Bridge on localhost. Decrypted mail never leaves the machine.
• Bridge needs a PAID Proton plan (Mail Plus / Unlimited). Free accounts can't run Bridge → can't use this. This scopes the audience; state it honestly everywhere (README does).
• Bridge hands out per-account generated IMAP/SMTP credentials — NOT the Proton login password.
• Bridge defaults: IMAP 1143, SMTP 1025, both STARTTLS with a self-signed cert. We trust the self-signed cert for localhost by default (allowSelfSigned, on) — expected for Bridge, not a smell.
• Bridge runs GUI on Mac/Win, headless via protonmail-bridge --cli on servers.

Architecture

Node, ESM, MCP over stdio (the client spawns us; stdout is JSON-RPC ONLY — all logging → stderr). Files in src/:

• index.js — bin entry (#!/usr/bin/env node). Builds the McpServer, registers tools, connects StdioServerTransport. Does NOT hard-fail on missing config (so the client can still list tools); individual tool calls throw a helpful error if unconfigured.
• config.js — loads config. Precedence: PROTONMAIL_* env → JSON file ($PROTONMAIL_MCP_CONFIG or ~/.config/proton-mail-bridge-mcp/config.json) → Bridge defaults. assertConfigured gives the friendly "you're missing X" error.
• mail.js — the only place that touches Bridge. Connect-per-operation (imapflow client built, connected, used, logged out each call) — deliberate: sporadic MCP calls + a parked IMAP socket goes stale, so reconnecting against localhost is the robust trade. withImap / withMailbox wrappers. IMAP via imapflow, SMTP via nodemailer, draft MIME via nodemailer's MailComposer (imported from nodemailer/lib/mail-composer/index.js — it's NOT a named export), parsing via mailparser simpleParser. "Delete" = move to Trash (never hard-expunge).
• format.js — cleanMessage turns parsed MIME into tidy JSON for an LLM; stripQuoted trims quoted reply history + -- signatures so summaries don't drown in forwarded chains (pass full:true to keep everything).
• tools.js — the MCP tool surface. Deliberately small: exactly 8 tools (Simon's scope call, 2026-08-17 — the "plain and simple" niche vs the 30-tool incumbent proton-mail-mcp): search_mail (no filter = recent inbox), get_message, download_attachment, create_draft, send_message, reply, reply_all, forward. READ (first 3) always registered; WRITE (other 5) skipped entirely when readOnly (→ 3 tools). guard() wraps every handler so a throw becomes a clean MCP error, not a dead server. The sharp tools (send/reply/reply_all/forward) are named + described so the client's per-tool approval is the gate — we don't reinvent approval, we make it obvious. reply/reply_all/forward send immediately unless draft:true (→ Drafts). Outgoing attachments: any write tool takes attachments: [localPath] — absolute or relative to cwd, ~-expanded, read off disk via nodemailer (attachLocal); forward carries the original's attachments as bytes too. The BrainBoxx angle: email a file straight out of the brain you're in. HTML email: compose/reply/forward accept body (plain) OR html (formatted); bodyParts() always adds a plain-text alternative (via htmlToText) so it's proper multipart/alternative, and replies/forwards quote the original as an HTML blockquote (quoteHtml). Reading HTML-only mail: format.js htmlToText fallback so get_message isn't blank on HTML-only messages. Deliberately CUT (do NOT re-add without Simon — "plain and simple" is the positioning): mark read/unread, move/archive/trash, folders/labels, bulk ops, analytics, threads.
• setup.js — npx proton-mail-bridge-mcp setup: interactive first-run wizard (the onboarding differentiator vs the incumbent). Mirrors Bridge's Mailbox details panel field-for-field so users paste via Bridge's copy buttons; masked password prompt (TTY only); tests IMAP and SMTP (verifySmtp, timeout-guarded) before saving via saveConfig (0600). Wired as an argv branch in index.js alongside doctor. ⚠️ Testing note: piped stdin drops buffered readline lines between questions — test with paced input or a pty, not a bare printf | node.
• doctor.js — npx proton-mail-bridge-mcp doctor: human-facing preflight. Connects, authenticates, lists mailboxes → setup problems surface here with a clear message, not mid-conversation. (Wire the doctor subcommand as an argv branch in index.js if we want proton-mail-bridge-mcp doctor rather than npm run doctor / a separate bin — currently it's scripts.doctor + standalone.)