Facteur

An MCP server for a Proton account. Claude, ChatGPT, Cursor or any MCP client can use it to read, search, organize and send your Mail through Proton Mail Bridge, look up and manage Pass items through Proton's official pass-cli, and read your Calendar.

Facteur is French for postman.

AI app ──HTTPS + OAuth──▶ Facteur ─┬─ IMAP/SMTP (private network) ──▶ Proton Mail Bridge
                                   ├─ pass-cli, signed in as a Pass agent ──▶ Proton Pass
                                   └─ calendar share links (ICS, read-only) ──▶ Proton Calendar

• Remote server with built-in OAuth 2.1. Add the URL as a custom connector in claude.ai, the Claude apps, ChatGPT or Claude Code, then approve it once in your browser. A static token also works for scripts.

• Per-connection permissions. Each app gets read, organize & drafts, and/or send. A read-only connection doesn't even see the other tools.

• Self-contained. Node 26 runs the TypeScript directly, so there is no build step. The only state is one JSON file and an audit log.

Tools

Proton Pass (only when PROTON_PASS_AGENT_TOKEN is set)

Proton Calendar (only when FACTEUR_CALENDARS is set)

Proton Calendar has no API or CalDAV, so this is read-only, through each calendar's share link.

The bulk tools (mark, move, label, delete) take either ids or a search, so "archive every newsletter from last month" is one call. A max guard refuses searches that match more than expected.

Prompts are included for clients that support them: triage_inbox, summarize_unread, draft_reply and clean_up_newsletters.

Message ids look like INBOX/4521: the mailbox, a slash, then the IMAP uid.

Related MCP server: proton-bridge-mcp

Security

Facteur holds the keys to a mailbox, so it is built to be safe to expose:

• Nothing is reachable without a token. /mcp requires an OAuth access token or the static API token. Tokens are 256-bit random, stored only as SHA-256 hashes, and expire after 1 hour. Refresh tokens rotate on every use, and reusing an old one revokes the whole connection.

• Only the owner can approve a connection. The consent page sits behind Cloudflare Access, where the server verifies the Access JWT itself, or behind an admin password. Approving shows the app's name and where it sends you back, and lets you untick permissions. PKCE (S256) is mandatory, redirect URIs must match exactly, and the authorization codes are single-use and last 5 minutes.

• Connections can be revoked at any time from the dashboard at /.

• Every change is audited. Each move, delete, label, draft and send is appended to /data/audit.jsonl with the app, the message ids, and for sends the recipients and subject (never the body).

• Pass secrets are opt-in, per app. Facteur signs in to Pass as a Pass agent: a token limited to the vaults you choose, revocable from Pass, with Proton's own audit log (pass-cli agent monitor facteur). Item lists and details never contain secret values. Values come only from pass_reveal, which needs the pass.reveal scope (unticked on the consent page) and a reason that Proton records. Apps without that scope get a one-time link (single use, 10 minutes, behind your sign-in), and the value goes from Pass to your screen without passing through the AI. The static API token can't reveal unless FACTEUR_API_TOKEN_SCOPES says so. pass-cli runs with argument arrays (no shell). New passwords go over stdin, never on the command line. The session lives in a private directory that isn't persisted.

• Email content is treated as untrusted. Bodies and attachments are wrapped in <email_body untrusted> markers. The server's instructions tell the model never to act on instructions found in mail, and to draft rather than send when unsure. The send tools are annotated as destructive and open-world, so clients ask before running them.

• Sending is limited to your own addresses. Mail can only go out from the addresses in FACTEUR_FROM.

• Hardened HTTP. Responses have a strict CSP with no scripts and no framing. Requests are rate-limited per IP, forms are same-origin only, and session cookies are HttpOnly with SameSite=Lax. The container runs as the unprivileged node user.

• Bridge never leaves the private network. Bridge's self-signed TLS is accepted only because the hop is internal. Set BRIDGE_TLS_VERIFY=true if your Bridge has a real certificate.

Threat model in one line: anyone who can reach the URL can register a client, but only you can approve it. Anyone holding a valid token can act on your mail within its scopes, so give apps only the scopes they need.

If you deploy from a public fork with a PaaS that builds pull-request previews (Coolify, Vercel...), turn previews off for this app. A preview build can inherit production secrets.

Run it

Docker (next to Bridge)

docker build -t facteur .
docker run -d --name facteur --network <bridge-network> -p 8080:8080 \
  -v facteur-data:/data --env-file .env facteur

See .env.example. The required variables are BRIDGE_USER and BRIDGE_PASSWORD, the Bridge password shown by info in the Bridge CLI, not your Proton password. HTTP mode also needs FACTEUR_PUBLIC_URL, plus either FACTEUR_ADMIN_PASSWORD or Cloudflare Access (FACTEUR_ACCESS_TEAM and FACTEUR_ACCESS_AUD).

GET /healthz checks the process, and GET /healthz?deep also checks the IMAP connection.

Proton Pass

With pass-cli signed in as yourself (pass-cli login), create an agent that sees only the vaults you choose, then give its token to Facteur:

pass-cli agent create --expiration 1y --vault Personal --vault Work facteur      # prints pst_…::…
pass-cli agent access grant facteur --vault-name Personal --role editor           # only if it may edit

Renew it before it expires with pass-cli agent renew --expiration 1y facteur. See what it accessed with pass-cli agent monitor facteur.

Proton Calendar

In Proton Calendar, go to Settings → Calendars → your calendar → Share → Share with anyone (full view) and copy the link. The link contains the key to the calendar, so treat it as a secret.

Behind Cloudflare Access (recommended)

1. Create an Access application for the whole host, limited to yourself.

2. Add a bypass application for /mcp, /token, /register, /revoke and /.well-known/*, since AI apps call those directly. Those paths are protected by the tokens.

3. Set FACTEUR_ACCESS_TEAM and FACTEUR_ACCESS_AUD. The consent page and dashboard then need no password.

Connect an app

The MCP URL is https://<your host>/mcp.

• claude.ai / Claude Desktop / Claude mobile: Settings → Connectors → Add custom connector → paste the URL → Connect → approve.

• Claude Code: claude mcp add --transport http facteur https://<your host>/mcp, then run /mcp to sign in. Or skip OAuth with --header "Authorization: Bearer $FACTEUR_API_TOKEN".

• ChatGPT: Settings → Connectors → Create → paste the URL, authentication OAuth.

• Cursor, VS Code, others: add a remote/HTTP MCP server with the URL. They discover OAuth on their own.

• Local stdio (Bridge on your machine): FACTEUR_TRANSPORT=stdio node src/main.ts with the Bridge variables set.

Develop

npm install
npm run check   # tsc, types only
npm test        # vitest
npm run dev     # needs a Bridge; see .env.example
FACTEUR_URL=http://localhost:8080/mcp FACTEUR_TOKEN=... npm run smoke   # end-to-end, never sends

Layout:

• src/mail/ holds everything that talks to Bridge: the IMAP pool, mailboxes, search, message parsing, composing and SMTP.

• src/mcp/ holds the tools, prompts and output formatting.

• src/http/ holds the OAuth server, consent pages and the MCP endpoint.

MIT licensed.