mailpouch

# mailpouch

> MCP server that gives AI agents permission-gated, audit-logged access to Proton Mail and generic IMAP accounts — it connects from the user's machine to local Proton Bridge or to the configured IMAP/SMTP server; selected MCP results go to the MCP host and may be sent to its configured model provider.

mailpouch connects to Proton Bridge over a local TLS socket. Email is decrypted by Bridge on the user's device; normal message caching is in memory and wiped on shutdown, but scheduled outbound messages persist recipients, subjects, and bodies in `~/.mailpouch-scheduled.json`, while the optional FTS5 index persists indexed subject/body content on disk. It works with Claude Desktop, Cline, and any MCP-compatible host over stdio or HTTP.

## Quick start (AI agents)

Get connected in this exact order. The server's own MCP `initialize` instructions repeat these steps.

1. **Add the MCP server** to your client config (this single form works everywhere — global install or not):

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

2. **Call `setup_status` FIRST.** It is always available — even before credentials are set or this agent is approved — and returns the single next action. Its `state` is one of:
   - `unconfigured` — credentials aren't set. Run `npx -y mailpouch setup --username <you@proton.me> --password-stdin` (the Proton **Bridge** password — Bridge app → Settings → IMAP/SMTP → Password — **not** the Proton login password), or ask the user to run `npx -y mailpouch-settings` for the interactive wizard.
   - `bridge-unreachable` — ask the user to start the Proton Bridge desktop app (signed in). Bridge listens on **127.0.0.1** (IMAP 1143, SMTP 1025).
   - `pending-approval` — **expected on first connect, not an error.** Every agent is gated behind a human Approve/Deny. Ask the user to open the settings UI (default `http://localhost:8766/#/agents`) and click Approve, then retry. You cannot approve yourself.
   - `ready` — call `get_connection_status` to confirm live auth, then use the mail tools.

3. **`npx -y mailpouch doctor`** prints the same diagnosis from a shell and exits non-zero until the install is `ready` — useful for scripted setup.

Credentials are entered on the user's machine and stored in the OS keychain (or `~/.mailpouch.json`, mode 0600); never ask the user to paste their password into the chat — the server injects it.

## Documentation

- [README.md](README.md): Full human-facing documentation — installation, configuration, permission presets, security model, and the canonical tool inventory.
- [README_FIRST_AI.md](README_FIRST_AI.md): AI agent guide — read this before calling tools. Covers runtime discovery, limits, error handling, operating guidelines, and escalation.
- [SECURITY.md](SECURITY.md): Security model, responsible disclosure policy.
- [CONTRIBUTING.md](CONTRIBUTING.md): Development setup and contribution guidelines.
- [docs/smtp-imap-config-reference.md](docs/smtp-imap-config-reference.md): SMTP/IMAP configuration reference.
- [docs/proton-bridge-overview.md](docs/proton-bridge-overview.md): Proton Bridge architecture overview.

## Key facts for agents

- **Up to 86 tools** (83 canonical in `src/config/schema.ts` `ALL_TOOLS`, plus 3 always-available meta-tools: `setup_status`, `request_permission_escalation`, `check_escalation_status`). SimpleLogin and Proton Pass tools are omitted from `ListTools` until configured.
- **Tool tiering**: `core` (27 categorized + 3 meta = 30 visible), `extended` (77 + 3 = 80), `complete` (default, 83 + 3 = 86). `ListTools` controls discovery/context; server-side permission and agent-grant gates control authorization. The 3 meta-tools are visible at every tier.
- **Permission presets**: `read_only` (default), `send_only`, `supervised`, `full`, `custom`. Enforced server-side. Agents cannot bypass them.
- **Remote auth (HTTP) is OAuth-only — every agent authenticates as its own client; there is no shared bearer token.** Interactive agents self-register (RFC 7591 DCR) and use `authorization_code` + PKCE, gated by a human Approve/Deny in the Agents tab. Headless agents (cron, CI) use a pre-approved *service account* and the OAuth `client_credentials` grant (own `client_id` + `client_secret`). Operators provision them with `mailpouch agent issue --name <n> --preset <preset>` (or the Agents-tab "+ Service account" button). Local stdio callers are gated too. Every authenticated call resolves to a distinct, revocable identity and is written to the per-agent audit log.
- **Human-gated escalation**: use `request_permission_escalation` + `check_escalation_status` to request temporary elevated access. A human must approve via browser UI or terminal.
- **Destructive tools** (delete/trash/spam, alias deletion, server lifecycle, and `pass_get`/`pass_totp`) require MCP elicitation confirmation or `{ confirmed: true }`.
- **Multi-account**: most tools accept an optional `account_id` argument to route to a specific configured account.
- **Settings UI**: `http://localhost:8766` — shows current preset, escalation requests, connection status, and the Agents tab (approve/deny agents, issue service accounts). Auto-starts with the daemon. Its Setup tab and the install wizard can write the MCP entry into a client's config (Connect a client → Write to Claude Code / Claude Desktop), choosing stdio or HTTP.
- **Transport**: stdio (default) or HTTP, chosen by `connection.remoteMode`. `MAILPOUCH_FORCE_STDIO=1` forces stdio for a single spawn even when `remoteMode: true`. `mailpouch daemon` runs the shared HTTP daemon (one IMAP connection for many clients) — required to use several hosts (e.g. Claude Code + cowork) at once, since mailpouch holds one instance per account.
- **Local FTS5 search**: `fts_search` queries a SQLite index on-device. Requires `better-sqlite3` and `fts_rebuild` to populate. Search terms never leave the machine.
- **Reminder system**: `remind_if_no_reply` queues a follow-up that fires if no reply arrives within N days. Persists across restarts.
- **Credentials** live in the OS keychain or config file at `~/.mailpouch.json` (mode 0600). Never ask the user for their Bridge password — the server injects it.

## Repository

- GitHub: https://github.com/chandshy/mailpouch
- npm: https://www.npmjs.com/package/mailpouch
- Install/run: `npx -y mailpouch` (no global install needed), or `npm install -g mailpouch`
- MCP SDK: 1.29+, Node.js ≥ 22