mailpouch

mailpouch is an MCP server that gives AI agents a typed, permission-gated, audit-logged tool surface over private-mail providers — Proton Mail (via Proton Bridge) and plain IMAP.

The pitch in one line: if you picked Proton Mail because you didn't want a third party reading your inbox, you don't suddenly want to hand a chatbot OAuth access to that same inbox so it can triage on your behalf. The usual "connect your email" integrations route everything through someone else's servers and ask for blanket scopes. Hand-rolled IMAP inside the agent is worse — no permission boundary, no audit trail, and the model holds your credentials in its context window. Neither option respects why you chose the provider in the first place.

mailpouch runs locally and speaks to Proton Bridge over a TLS socket on your own machine; nothing leaves the box unless you asked it to. Up to 86 tools (83 canonical plus 3 meta-tools) cover reading, sending, drafts, folders, search, analytics, optional aliases and Proton Pass, plus system control. Tool tiers and capability-aware listing keep unconfigured companion tools out of an agent's context. Every connecting client gets its own grant with folder allowlists, IP pins, per-tool rate caps, expiry, and account binding — all hashed-args in the audit log, never the values. Delete, trash, spam, alias removal, and sensitive Pass retrieval round-trip through MCP elicitation for human confirmation before they execute.

It is real because the primitives are real: OAuth 2.1 with PKCE S256, RFC 7591 dynamic client registration, RFC 8707 resource indicators, RFC 9728 protected-resource metadata, and an OAuth client_credentials grant so headless agents authenticate too — every agent gets its own gated, revocable identity. Credentials live in the OS keychain. A local FTS5 index with BM25 ranking handles phrase, boolean, prefix, and column-filter queries so your search terms never leave your laptop. Desktop notifications use native osascript / notify-send / powershell.exe with no added dependency; webhook dispatch auto-detects CloudEvents 1.0, Slack, or Discord, signs with HMAC, and retries with eight-attempt exponential backoff. So how do you point it at your Bridge install and wire up a client?

Read, compose, and manage your encrypted Proton Mail inbox from any AI assistant — over stdio or remote HTTP — with human-controlled permissions.

---

⚠ Proton Terms of Service Notice

This is an unofficial third-party tool that connects to Proton Mail through Proton Bridge's local IMAP/SMTP surface. It is not affiliated with, endorsed by, or authored by Proton AG.

Proton's Terms of Service (proton.me/legal/terms) §2.10 prohibits "accessing the Services through automated means (including but not limited to bots, scripts, or similar technologies)". The textual reading covers agentic / scripted workloads against Bridge even though Bridge itself is a sanctioned surface.

This server is designed to keep access user-initiated, not autonomous:

• Default permission preset is read_only. Sending, deletion, and folder mutation require explicit user opt-in via the settings UI.
• Destructive tools (delete / empty_trash / move-to-trash / move-to-spam / alias deletion / sensitive Pass retrieval) require explicit confirmation. With MCP elicitation-capable clients, the server prompts the user out-of-band before executing; non-elicitation clients must pass { confirmed: true }.
• Elevated permissions require out-of-band human approval (settings UI button or terminal), not an agent-only grant.
• The settings UI shows a first-run ToS acknowledgement the user must click through before credentials are accepted.

You remain the operator of your Proton account. Running this server against your own account is your decision to make under Proton's ToS; the authors disclaim responsibility for ToS compliance on your behalf.

---

What It Does

Proton Mail encrypts your email end-to-end, which means no third-party API can read it. Proton Bridge solves this by decrypting email locally. This MCP server connects to Bridge and gives Claude (or any MCP host) structured, permission-gated access to your inbox.

Your emails are decrypted on your own machine by Proton Bridge. This server never persists email content — everything stays in memory and is cleared on restart. You control exactly what the AI can do through a preset permission system with human-gated escalation for anything sensitive.

---

Quick Start (zero to running)

Prereq: Proton Bridge installed, running, and signed in.

1. Add the MCP server to your client. This one form works whether or not mailpouch is globally installed:

   { "mcpServers": { "mailpouch": { "command": "npx", "args": ["-y", "mailpouch"] } } }
   

2. Configure Bridge credentials — either path writes ~/.mailpouch.json (+ OS keychain):

   • Interactive wizard: npx -y mailpouch-settings
   • Non-interactive (scriptable / agent-driven): npx -y mailpouch setup --username you@proton.me --password-stdin (paste the Proton Bridge password — Bridge → Settings → IMAP/SMTP → Password — not your Proton login password)

3. Verify: npx -y mailpouch doctor — prints the exact next step until it reports ready. (Agents can call the always-available setup_status tool for the same diagnosis.)

4. Approve the agent. On first connect, every client is gated behind a one-time human Approve/Deny — open the settings UI (http://localhost:8766/#/agents) and click Approve. This is expected, not an error.

That's it. The sections below cover everything in depth.

---

Key Features

• Up to 86 tools — 83 canonical tools across 11 categories plus 3 always-available meta-tools (setup_status, request_permission_escalation, check_escalation_status). SimpleLogin and Proton Pass groups are listed only when configured. See src/config/schema.ts for the canonical inventory.
• Two transports — stdio (default, Claude Desktop) and HTTP (remote / self-host). HTTP is OAuth-only: authorization_code + PKCE-S256 for interactive agents and client_credentials for headless service accounts, with RFC 7591 Dynamic Client Registration, RFC 8414 authorization-server metadata, and RFC 9728 protected-resource metadata. Per-caller token-bucket rate limiting on every endpoint.
• Progressive tool tiering — core / extended / complete controls how many tools land in the client's ListTools response, so context isn't burned on tools you don't use. Configurable via toolTier or MAILPOUCH_TIER.
• Destructive-tool confirmation — uses MCP elicitation when the client supports it (Claude Desktop, Cline) so the user sees a prompt before delete, trash, spam, alias deletion, server lifecycle, or sensitive Pass retrieval. Falls back to a required { confirmed: true } argument for clients without elicitation.
• 5 permission presets — read-only by default; write access requires explicit opt-in. Per-tool overrides and rate limits via the Custom preset.
• Human-gated escalation — agents request elevated permissions, you approve via browser UI or terminal; the agent cannot approve its own requests.
• Browser-based settings UI at localhost:8766 — auto-starts with the daemon; setup wizard, live connection test, per-tool toggles, escalation approval panel, per-agent Approve/Deny.
• Native system tray icon — always visible, clickable menu opens the settings UI or quits. Rendered via a bundled Rust (napi-rs) binding around the tauri-apps/tray-icon crate — the same one Tauri ships in production — so the tray behaves correctly on modern GNOME (where the legacy Go-binary library shows a generic placeholder), NSStatusBar on macOS, and Shell_NotifyIcon on Windows. Prebuilts for linux-x64/arm64, darwin-arm64, win32-x64/arm64 ship inside the main package; darwin-x64 (Intel Mac) falls back to the legacy Go backend cleanly.
• 6 MCP prompts — triage inbox, compose reply, daily briefing, find subscriptions, thread summary, draft in my voice.
• MCP Resources — individual emails and folders addressable via email:// and folder:// URIs.
• Scheduled email delivery — queue emails for future sending; survives server restarts. Plus remind_if_no_reply for outbound follow-ups gated on inbox replies.
• Optional companion services — SimpleLogin alias management (16 tools, requires API key) and Proton Pass via pass-cli (4 tools, requires PAT) are omitted from ListTools until configured; local FTS5 full-text index remains available when better-sqlite3 is installed.
• TLS-strict by default — refuses to connect to localhost Bridge without a pinned cert, requires Bridge ≥ 3.22.0, exponential backoff on SMTP abuse-signal responses.
• Multi-account — configure more than one Proton / IMAP account; a running daemon hot-swaps the active account, while standalone settings and failed live rebinds explicitly request a restart. Tools accept an optional account_id argument to route a single call to a specific account. See src/accounts/.
• Per-agent grants — each MCP client (identified by its OAuth client_id) is gated by its own approvable grant, with optional folder allowlists, IP pins, per-tool rate caps, expiry, and account binding. Separate from the global preset and the escalation flow. See src/agents/.
• Live notifications — desktop toasts (no extra deps) and outbound webhooks (CloudEvents / Slack / Discord, HMAC-signed, retried) fire on grant-state changes. See src/notifications/.
• Strict TypeScript and a comprehensive Vitest suite; unused locals and parameters are compiler errors.

Documentation: HELP.md (task-oriented how-tos) · README_FIRST_AI.md (agent API reference) · docs/index.md (full index)

---

Quick Start

Ask Claude things like:

"Summarize everything from my boss this week"
"Find emails about my Acme invoice and draft a reply"
"Move all order confirmations to my Shopping folder"
"What's my average email response time this month?"
"Schedule a follow-up email to alice@example.com for next Monday at 9am"
"Remind me if there's no reply within 3 business days"

With read-only permissions (the default), Claude can read, search, and analyse your inbox but cannot send, move, delete, or change anything.

---

Prerequisites

| Requirement | Version | Notes | |---|---|---| | Node.js | >= 22.0.0 | Check with node --version · nodejs.org | | npm | >= 10.0.0 | Bundled with Node.js | | Proton Bridge | >= 3.22.0 | Must be running and signed in · proton.me/mail/bridge | | Proton Mail account | Paid plan | Bridge requires a paid Proton plan (Mail Plus, Unlimited, etc.) | | MCP client | Latest | Claude Desktop, Cline, or any MCP-compatible host · claude.ai/download |

Supported on macOS, Windows, and Linux.

Linux runtime libraries

The native tray binding dy