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.

Related MCP server: mail-mcp

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.

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, 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.

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

Supported on macOS, Windows, and Linux.

Linux runtime libraries

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:

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:

1. Welcome — overview, ToS acknowledgement, and prerequisites checklist

2. Bridge health check — live TCP test to ports 1025 and 1143; blocks progress until Bridge is reachable

3. Account — your Proton Mail address and Bridge password (Bridge app → Settings → IMAP/SMTP → Password — this is not your Proton login password)

4. Permission preset — choose what the AI is allowed to do (see table below)

5. Review — confirm your settings before saving

6. 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 you@proton.me --password-stdin

# or from a file, or inline; optional non-default ports / cert
npx -y mailpouch setup --username you@proton.me --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.)

Claude Desktop Configuration (stdio)

The config file locations are:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Canonical entry — works whether or not mailpouch is globally installed:

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

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):

{
  "mcpServers": {
    "mailpouch": {
      "command": "node",
      "args": ["/path/to/mailpouch/dist/index.js"]
    }
  }
}

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:

{
  "accounts": [
    { "id": "primary", "name": "Personal", "providerType": "proton-bridge",
      "smtpHost": "127.0.0.1", "smtpPort": 1025,
      "imapHost": "127.0.0.1", "imapPort": 1143,
      "username": "me@proton.me", "password": "<bridge-pw>" },
    { "id": "acct-7b1c", "name": "Work", "providerType": "imap", "...": "..." }
  ],
  "activeAccountId": "primary"
}

• 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.

Canonical code: src/accounts/registry.ts, src/accounts/manager.ts, src/accounts/types.ts.

Remote / HTTP Transport

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:

{
  "connection": {
    "remoteMode": true,
    "remoteHost": "127.0.0.1",
    "remotePort": 8788,
    "remotePath": "/mcp",
    "remoteTlsCertPath": "/path/to/cert.pem",
    "remoteTlsKeyPath":  "/path/to/key.pem",
    "remoteOauthEnabled": true,
    "remoteOauthIssuer": "https://mcp.example.com",
    "remoteRateLimitPerSecond": 20,
    "remoteRateLimitBurst": 40
  }
}

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:

{
  "mcpServers": {
    "mailpouch-remote": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <access_token>" }
    }
  }
}

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              # starts the shared HTTP daemon (forces HTTP; requires remoteOauthEnabled)
# optional: mailpouch daemon --host 0.0.0.0 --port 8788

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:

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.

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.

MCP Prompts

Pre-built prompt templates for common tasks:

Permission 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:

1. The agent calls request_permission_escalation with a reason and the target preset it needs.

2. A challenge appears as a banner in the Settings UI (above the tabs) and is also printed to the terminal.

3. You review the request, type APPROVE in the confirmation field, and click Approve (or Deny).

4. The agent polls with check_escalation_status and proceeds once approved.

5. 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

• Permissions — preset selector, per-tool enable/rate-limit toggles, tool-tier (core / extended / complete), destructive-confirm toggle

• 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:

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:

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.

Canonical code: src/agents/grant-store.ts, grant-manager.ts, audit.ts, caller-context.ts, notifications.ts, registry.ts.

Notification Channels

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.

Canonical code: src/notifications/desktop.ts, src/notifications/webhooks.ts.

Troubleshooting

"Connection refused" on Bridge ports

• Confirm Proton Bridge is running and signed in.

• Use 127.0.0.1 instead of localhost in all host fields.

• Verify ports are listening: lsof -i :1025 -i :1143 (macOS/Linux) or netstat -ano | findstr "1025\|1143" (Windows).

• Some VPNs block localhost port binding — try disabling the VPN.

"Authentication failed" or IMAP login error

• Use the Bridge password, not your Proton Mail login password.

• Find it in the Bridge app: Settings → IMAP/SMTP → Password (a long random string).

• If you recently reinstalled Bridge, it generates a new password — update it in the settings UI.

"Tool blocked by permission policy"

• Open the settings UI → Permissions tab and switch to Supervised or Full Access.

• Per-tool toggles let you enable individual tools without changing the overall preset.

• The agent can call request_permission_escalation for temporary access.

"Certificate error" or TLS handshake failure

• Export the Bridge TLS certificate: Bridge app → Settings → Export TLS certificates.

• 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:

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.

License

MIT — see LICENSE

Unofficial third-party server. Not affiliated with or endorsed by Proton AG.

GitHub · npm · Issues · Model Context Protocol