kingbin/proton-mcp

A read-only, local MCP server that lets an AI assistant read your Proton Mail through Proton Mail Bridge and save attachments into a local folder you choose (for example an Obsidian vault). It runs over stdio on macOS.
See SECURITY.md for the threat model and every control, and docs/DESIGN.md for the architecture.
## What it does
Four tools:
maillistmailboxes: lists the mailboxes you have allowed, with message counts.
mailsearch: searches an allowed mailbox by sender, subject, date range or attachments.
mailread: returns one message as plain text, wrapped in untrusted-content markers.
mailsaveattachment: saves one attachment into a folder you have allowed.
Every tool carries MCP annotations: the three mail tools are marked read-only; the save tool is marked as non-destructive (it only creates new files).
## What it does not do
It never sends, deletes, moves, flags, labels or marks mail as read. There is no code path that can.
It never returns mail from Spam or Trash. It reads only their envelopes, to collect Message-IDs, and refuses any message whose Message-ID also appears there.
It writes only to the folders you list in the config, its audit log (~/Library/Logs/proton-mcp/audit.log), and, when you run pin-cert, the pinned certificate file.
It never overwrites a file, and never connects anywhere except your local Bridge.
## Requirements
macOS (the Bridge password is read from the macOS Keychain).
Node.js 22 or newer.
Proton Mail Bridge, running and signed in.
## Install
git clone https://github.com/kingbin/proton-mcp.git
cd proton-mcp
npm ci
npm ci installs exactly the versions in package-lock.json, and its prepare step builds build/. If build/index.js is missing afterwards (for example with --ignore-scripts), run npm run build. npm install also works.
## Setup
1. Start Proton Mail Bridge and sign in.
2. In Bridge, export the TLS certificate (Settings > Export TLS certificates). Note the file path.
3. Pin it. This validates the file and stores only the certificate at ~/.config/proton-mcp/bridge-cert.pem (mode 600):
node build/index.js pin-cert /path/to/cert.pem
If Bridge's certificate ever changes, every call fails until you export and pin the new one. There is no trust-on-first-use.
4. Store the Bridge password in the Keychain. Use the Bridge username and the password Bridge shows for your account (not your Proton login password). -w with no value makes security prompt for it:
security add-generic-password -s proton-mcp -a -w
5. Create ~/.config/proton-mcp/config.json:
json
"bridge": { "host": "127.0.0.1", "port": 1143, "username": "you@example.com" },
"mail": { "allowedMailboxes": ["Labels/MCP"] },
"vault": {
"root": "/path/to/your/vault",
"allowedDestinations": ["Inbox", "Documents"]
},
"maxAttachmentBytes": 26214400,
"allowOfficeDocuments": false,
"allowMarkdown": false
host must be 127.0.0.1 or ::1.
allowedMailboxes lists the mailboxes the assistant may read. A dedicated label (here Labels/MCP) that you apply to the mail you want to share works well. Spam and Trash cannot be listed.
allowedDestinations is required and must list at least one folder, relative to root. Attachments can only be saved inside these folders (and their subfolders). Folders must already exist.