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 — MCP server for Proton Mail. 69 tools, local-only, permission-gated agentic email access via Proton Bridge.
Estrelas
17
Ferramentas
—
Disponibilidade
—
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. Message content is normally cached in memory and cleared on restart, but scheduled outbound messages persist recipients, subjects, and bodies in ~/.mailpouch-scheduled.json. The optional local FTS5 index uses ~/.mailpouch-fts.db (or MAILPOUCH_FTS_DB) as its base/legacy path, then stores live account indexes under the derived private <base-name>.accounts/<account-hash>.db locations. Protect or clear those stores as appropriate. 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.
Add the MCP server to your client. This one form works whether or not mailpouch is globally installed:
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.)
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, recommends Bridge ≥ 3.22.0 (older detected versions warn but do not block connection), and uses 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.
"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 [email protected] 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.
The native tray binding dynamically links against two GTK system
libraries that are preinstalled on every modern desktop Linux
distribution (Ubuntu ≥ 18.04, Fedora ≥ 34, Mint, Pop!_OS, Arch,
etc.). No manual install is needed on a normal desktop system —
just a note for server / container / minimal-WM deployments:
If both are missing (headless server, container, SSH-only host),
mailpouch's tray startup logs a skip reason and continues without
the icon — the MCP server itself runs unaffected. macOS and
Windows ship their native equivalents as part of the OS.
Proton Bridge ports
Bridge listens locally on:
Protocol
Host
Port
SMTP (sending)
127.0.0.1
1025
IMAP (reading)
127.0.0.1
1143
Use 127.0.0.1, not localhost. On some systems localhost resolves to ::1 (IPv6), which Bridge does not listen on.
Installation
Option A — npm (recommended)
npm install -g mailpouch
Or skip the install entirely — npx -y mailpouch runs the latest published version on demand, which is exactly what the canonical MCP client config below uses.
Option B — From source
git clone https://github.com/chandshy/mailpouch.git
cd mailpouch
npm install
npm run build
Optional companions
Install only if you plan to use the corresponding tool group:
Tools in unconfigured groups return a clean configuration error rather than failing silently.
Setup Wizard
Run the settings server to complete first-time setup:
npx -y mailpouch-settings
# Then open http://localhost:8766
The 6-step wizard walks you through everything automatically:
Welcome — overview, ToS acknowledgement, and prerequisites checklist
Bridge health check — live TCP test to ports 1025 and 1143; blocks progress until Bridge is reachable
Account — your Proton Mail address and Bridge password (Bridge app → Settings → IMAP/SMTP → Password — this is not your Proton login password)
Permission preset — choose what the AI is allowed to do (see table below)
Review — confirm your settings before saving
Done — displays the exact JSON snippet to paste into your MCP client config; optionally writes it for you automatically
Settings are saved to ~/.mailpouch.json with mode 0600 (owner read/write only). The Bridge password and SMTP token prefer the OS keychain when available.
Non-interactive setup (agents / CI)
When a browser/TUI wizard isn't an option, configure credentials from the command line — it writes the same ~/.mailpouch.json (+ keychain) the wizard does:
# password from stdin (keeps the secret out of the process list)
printf '%s' "$BRIDGE_PASSWORD" | npx -y mailpouch setup --username [email protected] --password-stdin
# or from a file, or inline; optional non-default ports / cert
npx -y mailpouch setup --username [email protected] --password-file ./bridge.pw \
[--imap-host 127.0.0.1 --imap-port 1143 --smtp-host 127.0.0.1 --smtp-port 1025] \
[--bridge-cert /path/cert.pem | --insecure]
Then check the install end-to-end:
npx -y mailpouch doctor # human-readable diagnosis + next step; exit 0 when ready
npx -y mailpouch doctor --json # structured output for scripts
npx -y mailpouch status # is it running? ports, connection, approved agents (read-only)
npx -y mailpouch --help # all commands + flags + the config/log paths
doctor reports the same state machine the always-available setup_status MCP tool returns: unconfigured → bridge-unreachable → pending-approval → ready, each with the exact action to advance. These commands print and exit — they never start a server, so they're safe to run alongside a live daemon. (Running mailpouch with no command starts the MCP stdio server, which is what your MCP client spawns.)
This is the same JSON shown in llms.txt and README_FIRST_AI.md — use it everywhere. If you installed globally (npm install -g mailpouch) you may instead use "command": "mailpouch" with no args. Restart the client after saving.
If you cloned the repo instead of installing from npm, point the client at the built entry file directly (your path will differ):
The settings wizard can also write the entry to your client config automatically — click Write to Claude Desktop on the Done step.
Multi-Account
More than one mail account can be configured in the same server — handy for juggling a personal Proton address, a work Proton address, and a generic IMAP account from a single MCP client.
The config file grows two fields alongside the existing connection block:
The Accounts tab in the settings UI handles add / edit / activate / delete. The server refuses to delete the last remaining account.
AccountManager keeps one { imap, smtp, spec } triple per configured account. In a running daemon, saving a new active selection emits an active-changed event that rebinds active-account services and clears prior-account caches. Standalone settings (or a failed live rebind) reports that a restart is required.
Tools accept an optional account_id argument. When omitted, the call runs against activeAccountId; when present, the dispatcher routes to the named account. Agent grants can pin a client to a single accountId via conditions.
Legacy single-account configs are migrated lazily: the first load with accounts: [] lifts the top-level connection fields into a primary account. No manual migration step.
For headless boxes, phones, or sharing one Bridge across multiple devices, switch to HTTP transport. The same binary listens on a port instead of stdio.
Enable it via the Setup tab → Remote (HTTP) mode, or by setting these in ~/.mailpouch.json:
Auth is OAuth-only — every agent authenticates as its own client. There is no shared bearer token (it was removed because it bypassed per-agent gating and audit). A verified token always maps to a specific, gated, revocable agent identity. remoteMode refuses to start without remoteOauthEnabled. Two grant types share the one listener:
authorization_code + PKCE-S256 (interactive agents) — MCP hosts self-register via POST /oauth/register (RFC 7591), discover endpoints via GET /.well-known/oauth-authorization-server (RFC 8414) and GET /.well-known/oauth-protected-resource (RFC 9728), then complete a PKCE flow with automatic consent (no admin password — GET /oauth/authorize issues a code immediately). The human gate is the per-agent Approve/Deny in the Agents tab: the issued token is inert until you approve the agent, and a pending request expires after 5 minutes.
client_credentials (headless / service accounts) — cron, CI, and scheduled agents that can't do interactive consent. Issue a service account out-of-band, then log in with its client_id + client_secret:
mailpouch agent issue --name nightly-triage --preset read_only
# → prints client_id + client_secret ONCE; the matching grant is pre-approved (active).
# also: mailpouch agent list / mailpouch agent revoke <client_id>
# (or use the "+ Service account" button in the Agents tab)
curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials https://mcp.example.com/oauth/token
# → { "access_token": "…", "token_type": "Bearer", "expires_in": 86400 }
Rate limiting — token-bucket per caller (per IP for unauthed paths, per token key for /mcp). A compromised token can't DoS Bridge.
TLS — provide remoteTlsCertPath + remoteTlsKeyPath for HTTPS. Required for any non-loopback exposure.
A remote client config (after obtaining an access token via either grant) looks like:
Connecting a client (stdio or HTTP). The Settings UI (Setup tab → Connect a client) and the first-run wizard both let you choose how an MCP client connects and write the entry for you:
Write to Claude Code merges a mailpouch entry into ~/.claude.json under mcpServers (and Write to Claude Desktop does the same for claude_desktop_config.json).
stdio — the client spawns its own mailpouch. The written entry sets MAILPOUCH_FORCE_STDIO=1 so it speaks stdio even when your config has remoteMode: true. Don't run a stdio client alongside the shared HTTP daemon against the same Proton account — they'd contend for the one IMAP connection.
HTTP — the client connects to the shared daemon at /mcp (needs remoteMode + remoteOauthEnabled and the daemon running). The client performs an OAuth login and you Approve it once in the Agents tab.
Running mailpouch as a shared daemon (multiple apps at once). mailpouch holds one IMAP connection per account (a singleton lock), so two stdio instances for the same account can't run at the same time — the second exits. To use several clients together (e.g. Claude Code and Claude cowork, or headless agents), run one HTTP daemon and point every client at it:
mailpouch daemon is user-started (run it in a tmux / login session or your own supervisor) — it is not an autostart. Then:
Interactive apps (Claude Code, Claude Desktop) connect over HTTP and you Approve each once in the Agents tab.
Headless / cowork hosts authenticate with a per-host service account (mailpouch agent issue --name <host> --preset <preset>) over the client_credentials grant.
All clients share the daemon's single IMAP connection — no singleton conflict, and each is independently gated, audited, and revocable.
While the daemon is running, the Settings "Connect an app" chooser only offers HTTP — the per-computer (stdio) option is disabled, because a stdio entry would spawn a second instance that collides with the daemon and fail to start. Issuing or re-issuing a service account (mailpouch agent issue) takes effect immediately — the running daemon picks it up on the next login, no restart. Revoking a service account (in the Agents tab) deletes its credential, so it stays revoked across restarts; to re-enable, re-issue it.
Environment variables
Configuration is stored in ~/.mailpouch.json and managed via the settings UI — not environment variables. The following env vars are available for advanced/optional overrides:
Variable
Default
Description
MAILPOUCH_CONFIG
~/.mailpouch.json
Override config file path
MAILPOUCH_SCHEDULER_STORE
~/.mailpouch-scheduled.json
Scheduled email persistence file
MAILPOUCH_LOG_FILE
~/.mailpouch.log
Override log file path
MAILPOUCH_PENDING
~/.mailpouch.pending.json
Override pending escalations file path
MAILPOUCH_AUDIT
~/.mailpouch.audit.jsonl
Override escalation audit log path
MAILPOUCH_REMINDERS
~/.mailpouch-reminders.json
Override reminder persistence file path
MAILPOUCH_PASS_AUDIT
~/.mailpouch-pass-audit.jsonl
Override Proton Pass access audit log path
MAILPOUCH_FTS_DB
~/.mailpouch-fts.db
Override full-text-search index database path
MAILPOUCH_AGENTS
~/.mailpouch-agents.json
Override per-agent grant store path
MAILPOUCH_SERVICE_ACCOUNTS
~/.mailpouch-service-accounts.json
Override service-account (client_credentials) store path
MAILPOUCH_AGENT_AUDIT
~/.mailpouch-agent-audit.jsonl
Override per-agent tool-call audit log path
MAILPOUCH_MACHINE_SECRET
derived from host
Override the machine-binding secret used to encrypt at-rest credentials
MAILPOUCH_FORCE_STDIO
unset
Force stdio for this spawn even if the config has remoteMode: true. Set on a stdio MCP-client entry (e.g. Claude Code) so it speaks stdio instead of starting the HTTP server.
MAILPOUCH_INSECURE_BRIDGE
unset
Per-launch opt-in to localhost Bridge without a pinned cert
MAILPOUCH_TIER
complete
Tool-tier override: core (30 tools), extended (80), or complete (up to 86, depending on optional integrations)
PORT
8766
Override settings UI HTTP server port
Available Tools
83 canonical tools across 11 categories, plus 3 always-available meta-tools. Optional companion groups are listed only when configured; see src/config/schema.ts for the machine-checkable inventory.
Category
Tools
Default tier
Risk
Permission required
Reading
14
core
safe
always available
Sending
4
core
moderate
supervised, send_only, full
Analytics
4
core
safe
always available
System
5
core
safe
always available
Drafts & Scheduling
9
extended
moderate
supervised, send_only, full
Folder Management
5
extended
moderate
supervised, full
Email Actions
16
extended
moderate
supervised, full
SimpleLogin Aliases (optional)
16
extended
moderate
listed when API key is present
Proton Pass (optional)
4
extended
moderate
listed when a PAT is present; calls require pass-cli
Deletion
3
complete
destructive
full (capped at 20/hr in supervised)
Bridge & Server Control
3
complete
destructive
mixed; start_bridge always available
Plus 3 always-available meta-tools: setup_status, request_permission_escalation, and check_escalation_status.
Notable tools worth calling out
Reading includes get_thread, get_correspondence_profile, and the fts_* family (local SQLite FTS5 index — much faster than IMAP search for repeat queries).
Drafts & Scheduling includes remind_if_no_reply (queue an outbound, fire a follow-up reminder if no reply lands within N days), list_pending_reminders, cancel_reminder, check_reminders. JSONL persistence so reminders survive restarts.
Bridge & Server Control — if autoStartBridge is enabled, the server launches Bridge automatically on startup and runs a 30 s watchdog that attempts up to 3 restarts on outage. shutdown_server and restart_server are capped at 5/hr in supervised.
Identify mailing lists / newsletters; offer to archive or unsubscribe
folder (default: INBOX)
thread_summary
Fetch all messages in a thread; produce a concise summary with open action items
emailId (required)
draft_in_my_voice
Draft a new email to a specific recipient in the user's own voice, using a handful of recent sent emails as tone samples. Infers style (formality, greeting/sign-off habits, typical length) from the samples.
recipient (required), intent (required), sampleCount (optional, default 5, max 20)
User-defined per-tool toggles and rate limits (set via the Permissions tab)
Fine-grained control beyond the 4 presets
Change the preset at any time from the Permissions tab in the settings UI; changes take effect within 15 s without restart.
Human-Gated Escalation
The escalation system lets an agent request broader permissions without permanently changing your settings.
How it works:
The agent calls request_permission_escalation with a reason and the target preset it needs.
A challenge appears as a banner in the Settings UI (above the tabs) and is also printed to the terminal.
You review the request, type APPROVE in the confirmation field, and click Approve (or Deny).
The agent polls with check_escalation_status and proceeds once approved.
After 5 minutes, permissions revert automatically.
Security properties:
The agent requests via MCP; approval can only happen via browser or terminal — channels the agent cannot write to
You must type APPROVE before the button activates — no accidental clicks
CSRF-protected: the approval API requires a session token embedded only in the rendered HTML page
Rate-limited: max 5 escalation requests per hour, max 1 pending at a time
Audit trail: every request, approval, and denial is appended to ~/.mailpouch.audit.jsonl
Approve from another device: npx -y mailpouch-settings --lan
Settings UI
The settings UI starts automatically on http://localhost:8766 whenever your MCP client runs the server. A system tray icon (purple envelope) appears in your taskbar — right-click it to open the UI, disable it temporarily, or quit.
To run the settings UI standalone (useful for initial setup, headless / SSH systems, or a dedicated remote-mode host):
npx -y mailpouch-settings # auto-detects display; opens browser if available
npx -y mailpouch-settings --port 9000 # custom port (default: 8766)
npx -y mailpouch-settings --lan # bind to 0.0.0.0 (approve from phone/other device)
npx -y mailpouch-settings --browser # force browser UI even if no display detected
npx -y mailpouch-settings --tui # force interactive terminal UI
npx -y mailpouch-settings --plain # plain readline menus (no ANSI colors/escapes)
npx -y mailpouch-settings --no-open # start server but don't auto-open browser
The same standalone behaviour is available from the main binary via mailpouch --settings-only: it starts only the settings UI + tray (no MCP transport, no Bridge connect) and stays running until you quit it from the tray or with Ctrl-C. Unlike a bare mailpouch, it is safe to launch detached (autostart / nohup / a wrapper) — it does not tie its lifetime to stdin.
Tabs:
Setup — credentials, SMTP/IMAP hosts and ports, Bridge TLS certificate, Optional Integrations (SimpleLogin API key, Proton Pass PAT + CLI path), debug mode, auto-start Bridge, insecure-connection toggle, destructive-confirm toggle, desktop notifications toggle, auto-open approval window toggle, settings port
Accounts — per-account Bridge credentials; live active-account switching with an explicit restart fallback
Agents — per-client (OAuth client_id) approvable grants with folder allowlists, IP pins, per-tool rate caps, expiry, and account binding
Status — server info, MCP config snippet, live connectivity check, escalation audit log, config reset
Pending escalation requests appear as a full-page banner above the tabs. A Logs tab appears automatically when debug mode is enabled. Most settings changes propagate to the running MCP server within 15 s; active-account switching explicitly reports when a restart is required.
Security
This server gives AI agents controlled access to sensitive email data. The security model has these layers:
Layer
Mechanism
Permission gate
Every tool call checked against ~/.mailpouch.json (refreshed every 15 s)
Tool tiering
core / extended / complete controls the ListTools surface and context budget; permission gates remain the enforcement boundary
Rate limiting
Per-tool sliding-window limits in-process; per-caller token-bucket on the HTTP transport
Destructive confirmation
MCP elicitation prompt (or required { confirmed: true }) on delete / trash / spam, SimpleLogin deletion, server lifecycle, and sensitive Pass retrieval
Escalation gate
Privilege increases require explicit human approval via a separate channel
Audit log
Append-only log of all escalation events at ~/.mailpouch.audit.jsonl
OAuth 2.1 + PKCE-S256
Spec-compliant DCR + automatic consent; per-agent Approve/Deny is the human gate (HTTP transport)
CSRF protection
All mutating settings API calls require a session token (timing-safe comparison)
Origin validation
Settings server validates Origin/Referer headers; rejects unknown origins
CRLF stripped from all SMTP headers, subjects, filenames, custom headers
TLS-strict Bridge
Refuses to connect to localhost Bridge without a pinned cert by default
Bridge version floor
Warns when Bridge < 3.22.0 (FIDO2 + 50 MB import cap hardening)
SMTP backoff
Exponential backoff on abuse-signal SMTP responses (4xx 421/450/454 throttle codes)
Config file isolation
Mode 0600; preset and tool names validated on load; config schema versioned
Memory safety
Email cache capped at 500 entries / 50 MB; rate-limiter buckets evicted when idle (fully refilled)
Keychain storage
OS keychain preferred for Bridge password and SMTP token
What agents cannot do:
Approve their own escalation requests
Bypass the permission gate (it runs in the server process, not the agent)
Read or modify ~/.mailpouch.json directly (not an exposed tool)
Erase the audit log
Inject headers into outgoing email via crafted subjects, filenames, or custom headers
Execute destructive tools without surfacing the intent to the user
Credentials: Stored in ~/.mailpouch.json with 0600 permissions (or in the OS keychain). Never commit this file. The settings UI never displays or transmits high-value secrets after they are first saved.
Agent Grants
The global permission preset gates what actions are allowed; the selected tool tier controls what is advertised; and an agent grant gates which MCP client may use that allowed surface. Every agent — local and remote — registers and must be approved. A remote MCP host completes OAuth Dynamic Client Registration and mailpouch creates a pending grant keyed by its client_id; a local stdio client (e.g. Claude Desktop) is registered at the MCP handshake, keyed by its self-reported client name (stdio:<hash>) and shown with a 🖥 local marker. Nothing that client calls will succeed until you approve it; approve once and a local client is remembered across relaunches. To restore the legacy "local client is auto-trusted" behavior, set gateLocalAgents: false (or MAILPOUCH_TRUST_LOCAL=1).
Grant lifecycle: pending → active → revoked | expired. Each grant carries:
Field
Purpose
preset
Effective preset for this agent; intersected with the global preset (grants can never widen the ceiling)
toolOverrides
Per-tool allow/deny that trumps the preset, still bounded by the global config
conditions.expiresAt
ISO-8601 auto-expiry; checked at call time
conditions.folderAllowlist
Restrict which IMAP folders the agent may touch
conditions.ipPins
Allowed remote IPs (OAuth/bearer path only)
conditions.maxCallsPerHourByTool
Per-tool hourly rate cap
conditions.accountId
Bind the agent to a single multi-account id
Approve, deny, revoke, and "approve-with-conditions" all live in the Agents tab of the settings UI. The tab streams live updates over SSE from GET /api/notifications — new pending grants surface without a reload. When a new agent registers, mailpouch also auto-opens this tab in your browser (and fires a desktop notification + tray badge) so you can approve or deny the connection right away; the pending card shows the agent's name, registering IP, and time. The agent's tool calls stay blocked until you approve. When a new agent connects, mailpouch pops a native Approve/Deny dialog right on the screen where it runs (zenity/osascript/PowerShell) so you can decide without opening the tab — Approve grants your global preset, Deny revokes it (nativeApprovalDialog, default on). If no dialog tool is available (headless), it falls back to auto-opening this Agents tab in your browser (autoOpenApprovalWindow, default on) plus a desktop notification + tray badge. Once connected, the card also shows the agent's MCP handshake connection info — its self-reported client name + version, the transport, and a last-connected timestamp — captured at initialize (display-only; the agent's identity is its server-issued OAuth client_id, not the self-reported name).
Every agent authenticates as its own client — there is no shared bearer. The static bearer was removed because it had no per-agent identity (one secret, no gating, no audit). Remote mode requires OAuth (connection.remoteMode: true + remoteOauthEnabled: true). Interactive agents register and you Approve/Deny them here (automatic consent — no human password; a pending request expires after 5 minutes). Headless agents (cron, CI) use a pre-approved service account (mailpouch agent issue … or the "+ Service account" button) and the client_credentials grant. Deprecated remoteBearerToken and remoteOauthAdminPassword values are ignored and scrubbed from config/keychain storage during startup migration.
Every gated tool call writes one row to an append-only JSONL audit log at ~/.mailpouch-agent-audit.jsonl (mode 0600). Rows carry a truncated sha256 argHash — never argument values, never response bodies — so "same call repeated" patterns are observable without creating a parallel on-disk copy of your email. The log rotates at 10 MB and keeps 3 gzipped generations.
Caller identity propagates through the dispatcher via AsyncLocalStorage (see src/agents/caller-context.ts); the caller's clientId is always a real per-agent identity (pmc_… for OAuth clients and service accounts, stdio:… for local stdio agents). Local stdio agents are gated too (gateLocalAgents, default on) — they register and must be approved like any other agent.
Grant-state transitions (grant-created / -approved / -denied / -revoked / -expired) fan out through an in-process NotificationBroker to two optional channels:
Desktop toasts — platform-native, no extra dependency. macOS shells to osascript, Linux to notify-send (libnotify), Windows to powershell.exe driving the WinRT toast API. Fire-and-forget; missing tooling degrades to a debug log.
Outbound webhooks — WebhookDispatcher POSTs a JSON body to each configured endpoint. Format defaults to CloudEvents 1.0; URLs on hooks.slack.com auto-select the Slack shape and discord.com / discordapp.com auto-select the Discord shape (explicit format: "raw" is also available). When an endpoint has a secret configured, every body is HMAC-signed as X-Mailpouch-Signature-256: sha256=<hex> (GitHub-webhook convention). Delivery retries up to 8 times with exponential backoff (1 / 2 / 4 / 8 / 16 / 32 / 64 / 128 s) plus ±20 % jitter; 4xx responses other than 408 and 429 stop retries immediately.
Set the path in the settings UI under Setup → Bridge TLS Certificate.
The server refuses to connect to a localhost Bridge without a pinned TLS certificate — this matches Proton Bridge's own v3.21.2+ hardening. If you cannot provide a cert, set Allow insecure Bridge connection under Setup (or launch with MAILPOUCH_INSECURE_BRIDGE=1) to opt back into the legacy behavior. Configs that predate this change are grandfathered into the legacy mode with a startup warning until the opt-in is set explicitly.
Bridge version warning on startup
The server issues an IMAP ID request after connect and warns when Bridge is older than 3.22.0 (the recommended minimum); the version probe is warn-only and does not block connection. Upgrade from the Bridge app → Check for updates.
Tool list looks short / missing tools
Check your tool tier under Permissions. core exposes 30 tools; extended exposes 80; complete exposes up to 86, with unconfigured SimpleLogin and Pass tools omitted.
SimpleLogin and Proton Pass tools (alias_*, pass_*) appear once their API key or PAT is configured. The fts_* tools remain listed and require better-sqlite3 when called.
Remote / HTTP client returns 401
The Authorization: Bearer <token> header must carry an OAuth access token, not a pre-shared secret — the static bearer was removed. For interactive clients, check that /oauth/register succeeded, the agent is approved in the Agents tab, and the token has not been revoked or expired.
For headless clients, confirm the service account exists (mailpouch agent list) and that POST /oauth/token with grant_type=client_credentials returned an access_token. A 401 invalid_client means the client_id/client_secret pair is wrong.
The WWW-Authenticate header on the 401 response carries the failure reason per RFC 6750.
Claude Desktop doesn't show mailpouch tools
Confirm the mcpServers block is valid JSON (no trailing commas).
Fully quit and reopen Claude Desktop.
Check MCP logs: Help → Show Logs.
Verify the server starts manually: npx -y mailpouch — it should stay running silently.
Analytics show zero or empty data
Run sync_emails first to populate the cache.
Response time stats only appear when sent emails have In-Reply-To headers matching inbox messages.
Development
git clone https://github.com/chandshy/mailpouch.git
cd mailpouch
npm install
npm run build # compile TypeScript to dist/
npm run dev # watch mode (recompiles on save)
npm run test # run the Vitest suite
npm run test:coverage # coverage report
npm run lint # TypeScript type check (tsc --noEmit)
npm run settings # start standalone settings UI (after build)
Project structure
src/
index.ts # Unified daemon: MCP server (up to 86 tools, resources, prompts) + settings + tray
settings-main.ts # Standalone settings UI CLI (for headless/SSH environments)
# (Tray moved to native/tray/ — napi-rs binding around tauri-apps/tray-icon)
config/
schema.ts # Tool registry, categories, tiers, destructive set, response limits
loader.ts # Config load/save, preset builder, keychain migration
permissions/
manager.ts # Per-tool permission checks and rate limiting
escalation.ts # Human-gated escalation challenge system
security/
keychain.ts # OS keychain integration (@napi-rs/keyring)
memory.ts # Credential wipe helpers
services/
smtp-service.ts # Email sending via Nodemailer (with abuse-signal backoff)
simple-imap-service.ts # Email reading via ImapFlow
analytics-service.ts # Email analytics computation
scheduler.ts # Scheduled email delivery (JSONL persistence)
reminder-service.ts # remind_if_no_reply queue
fts-service.ts # Local SQLite FTS5 index (optional better-sqlite3)
simplelogin-service.ts # SimpleLogin alias API client
pass-service.ts # Proton Pass via pass-cli subprocess
settings/
server.ts # Browser-based settings UI server
security.ts # CSRF, origin validation, TLS
tui.ts # Terminal UI for settings
transports/
http.ts # HTTP transport with required OAuth 2.1 authentication
oauth-handlers.ts # /.well-known + /oauth/* (RFC 7591/8414/9728)
oauth-store.ts # Client / authorization-code / token store
rate-limit.ts # Token-bucket per-caller limiter
utils/
helpers.ts # ID generation, email validation, log sanitisation
logger.ts # Structured log store
tracer.ts # Lightweight request tracing
backoff.ts # Exponential backoff helper
types/
index.ts # Shared TypeScript types
Works Best With…
mailpouch is deliberately scoped to email. Chain it with these MCP servers to cover the rest of an agentic workflow:
Archive important threads to notes with linked metadata
The project is intentionally Proton-focused; the positioning is "best email surface for your agent." Pair it with whichever non-email MCPs fit your workflow rather than waiting for this server to grow a second home.
Acknowledgements
This project is built on the foundation originally created by Hawk94, whose initial IMAP/SMTP integration, tool architecture, and test setup made this project possible. The original work was published as barhatch/protonmail-mcp-server.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Mailpouch?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Mailpouch precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Mailpouch usa?
Mailpouch roda localmente via stdio.
Quando Mailpouch foi verificado pela última vez?
Última verificação: 2026-11-10. mailpouch — MCP server for Proton Mail. 69 tools, local-only, permission-gated agentic email access via Proton Bridge.