proto-mcp

A signed, notarized, Touch-ID-gated bridge between Proton Mail and Claude — running entirely on your Mac.

proto-mcp exposes 29 Model Context Protocol tools that let Claude Desktop and Claude Code read, search, compose, label, and send Proton Mail on your behalf. Every write is gated by a per-tool YAML policy and a macOS Touch ID prompt that shows the literal recipients and subject before the message goes out. Every call writes a redacted row to a local audit log. Nothing leaves your laptop except the mail itself.

Status: v1.0.0-alpha. Phase 1–6 merged; Phase 7/A (UX), 7/B (log rotation + polish), 7/C (signing + notarization + binary integrity) all merged. 7/D (OS-level Keychain ACL) is blocked on a provisioning profile and deferred to 7/E (.app bundle). 7/E (Homebrew + AppVersion + release CI) in progress. Personal-use, technical-audience early access. Read the caveats below before installing.

---

What you get

Class	Tools
Read	mail_list, mail_search, mail_read, mail_read_thread, mail_list_attachments, labels_list, folders_list, account_whoami, mail_sync
State	mail_mark_read, mail_mark_unread, mail_move, mail_label, mail_trash
Labels & folders	labels_create, labels_update, labels_delete, folders_create, folders_update, folders_delete
Drafts	mail_draft_create, mail_draft_update, mail_draft_delete, mail_draft_list
Send	mail_send, mail_reply, mail_reply_all, mail_forward, mail_send_draft
Reserved	mail_delete_permanent (denied by default; opt-in via policy)

29 callable tools; one explicit deny-by-default.

Architecture (Phase 6 daemon model)

                Claude Desktop          Claude Code
                      │                       │
              (stdio, JSON-RPC over NDJSON per MCP spec)
                      │                       │
                      ▼                       ▼
              protonmcp-shim        protonmcp-shim       <- one per client
                      │                       │            (tiny stdio↔socket forwarder)
                      └────── Unix socket ────┘
                              (0600, in ~/Library/Application Support/protonmcp/)
                              ▼
                       protonmcpd                          <- one long-running daemon
                              │                              (LaunchAgent, KeepAlive)
                              │
              ┌──────────────┬──────────────┬──────────────┬──────────────┐
              │              │              │              │              │
        internal/proton  internal/store  internal/policy  internal/      internal/audit
        (go-proton-api  (SQLite mirror,  (default.yaml + (Swift Touch  (SQLite + JSONL,
          + GPG)        FTS5, body cache,  user override) ID helper)    rotated at 50MB)
                        SQLCipher TBD)

protonmcp serve-stdio is the old single-process mode — still runnable for power users, but the default install registers the shim with Claude clients so multiple clients share one daemon and one Touch-ID-unlocked session.

Security model

The Keychain item that holds your Proton session is sealed behind three layers:

1. macOS Keychain encryption — the standard at-rest protection for any keychain item. Anything below assumes the user is logged in and the keychain is unlocked.
2. Touch ID at session-acquire time — the daemon prompts for biometric (or password fallback per Apple's .deviceOwnerAuthentication) on every startup AND every protonmcp unlock after a manual or auto-lock. The prompt is application-issued via the Swift helper. An OS-level SecAccessControl on the keychain item was prototyped in 7/D but reverted (needs an Apple-provisioned profile / .app bundle — tracked as D37, deferred to 7/E).
3. Per-call approval — every prompt-gated tool (everything that writes) fires a custom NSAlert + Touch ID prompt showing the literal recipients and subject. Cached approvals expire per policy TTL; mail_send has TTL 0, so every send re-prompts.

Plus:

• Hardened-runtime + Developer-ID-signed + Apple-notarized binaries. Gatekeeper accepts them without the "developer unknown" dialog.
• SHA-256 binary integrity check at daemon startup. If protonmcpd was replaced between install and launch, the daemon refuses to start.
• SO_PEERCRED / LOCAL_PEERPID on every shim connection — the daemon records the real connecting client's PID + UID in audit rows.
• Default-deny policy for unknown tools. Adding a new tool without a policy stub fails registration; you can't accidentally ship an unguarded write.
• Auto-lock triggers: screen lock, sleep, and idle_lock_minutes. Walking away from your laptop locks the daemon; unlocking requires Touch ID.
• Redacted audit log. Passwords / tokens / cookies become [REDACTED]. Bodies become {sha256, bytes}. Recipient addresses stay literal (so the prompt verification chain is honest).

SECURITY.md has the audit trail and per-defect fix log. DEFECTS.html is the open issue list (currently 5 open / 33 resolved; the open set is all medium / low).

Install

Two paths. Homebrew (signed + notarized binaries, recommended) once the first tagged release is up; build from source for contributors and pre-release testing.

Homebrew (Phase 7/E — pending first tagged release)

brew tap just-an-oldsalt/proto-mcp
brew install --cask proto-mcp
protonmcp login                   # interactive: SRP + TOTP + key unlock
protonmcp backfill                # one-time: drains every message envelope
protonmcp daemon install          # registers + starts the LaunchAgent
protonmcp install                 # registers shim with Claude Desktop + Claude Code

(The cask is proto-mcp with a hyphen; the binaries it installs keep their existing names protonmcp, protonmcpd, etc.)

The cask installs all five binaries into the Homebrew prefix's bin/ (signed + notarized; no Gatekeeper warning). brew uninstall --cask proto-mcp reverses everything; --zap also removes ~/Library/Application Support/protonmcp, ~/Library/Logs/protonmcp, and the LaunchAgent plist.

Build from source

Requires macOS 13+, Go 1.26+, and Xcode Command Line Tools (for swiftc).

git clone https://github.com/just-an-oldsalt/proto-mcp.git
cd proto-mcp
make all                          # builds bin/* + Swift helpers
./bin/protonmcp login             # interactive: SRP + TOTP + key unlock
./bin/protonmcp backfill          # one-time: drains every message envelope
./bin/protonmcp daemon install    # registers + starts the LaunchAgent
./bin/protonmcp install           # registers shim with Claude Desktop + Claude Code

Source builds are ad-hoc signed by default. For a signed-locally build, see scripts/signing-setup.md.

Restart Claude Desktop / Claude Code after either install path. The 29 tools show up under protonmcp in /mcp.

A Touch ID prompt looks like this

When Claude says "move 'Re: gear list' from inbox to archive," the NSAlert that fires says exactly that — not a redacted argument dump. Specifically:

┌──────────────────────────────────────────────┐
│ protonmcp-touchid is trying to              │
│ move message 'Re: gear list' from inbox      │
│ to Archive                                   │
│                                              │
│ Touch ID or enter your password to allow.   │
│              [ Cancel ]    [ Touch ID ]      │
└──────────────────────────────────────────────┘

The verb phrase comes from a per-tool PromptBody closure (internal/mcptools/prompt_helpers.go) that looks up message_id → Subject and label_id → Name from the local SQLite mirror. You read what you're approving.

For sends, the format is stricter:

┌──────────────────────────────────────────────┐
│ Send mail_send?                              │
│                                              │
│ To: alice@example.com                        │
│ CC: charlie@example.com                      │
│ Subject: Re: gear list                       │
│                                              │
│ [ Cancel ]              [ Send & Touch ID ]  │
└──────────────────────────────────────────────┘

Body content is replaced with a SHA-256 reference in the audit log but the recipient list is always verbatim in the prompt — that's the verification surface you tap against.

Configuring policy

Defaults are in internal/policy/default.yaml (embedded into the binary). Override per-tool by creating ~/Library/Application Support/protonmcp/policy.yaml:

tools:
  mail_send:
    decision: prompt
    confirm: true
    rate_limit: 5/hour                       # cap LLM-driven sends
    allowed_recipients: ["@mydomain.com"]    # restrict to one domain
  mail_delete_permanent:
    decision: deny                           # default; remove this to enable with prompt

# Phase 7/A — auto-lock idle timer
idle_lock_minutes: 30                        # lock if no tool call for 30 minutes (0 = disabled)

Reload without restarting:

./bin/protonmcp policy reload      # SIGHUP to every running daemon / serve-stdio
./bin/protonmcp policy show        # print the merged effective policy
./bin/protonmcp policy validate ./my-policy.yaml

Rate-limit buckets persist to SQLite (Phase 6/E), so a daemon restart doesn't reset the per-hour cap.

Locking

./bin/protonmcp lock      # SIGUSR1 — daemon zeros its in-memory session
./bin/protonmcp unlock    # SIGUSR2 — Touch ID prompt re-acquires from Keychain

The daemon also auto-locks on:

• macOS screen lock (com.apple.screenIsLocked distributed notification)
• system sleep (NSWorkspaceWillSleepNotification)
• idle timeout (idle_lock_minutes policy field; default 0 = disabled)

While locked, every tool call returns daemon is locked (<reason>); run \protonmcp unlock` to resume`. No audit row is written for the attempt (logged at WARN instead).

Observability

Two log destinations, both auto-rotated at 50MB × 10 generations (Phase 7/B):

# Tail the audit log (one JSON object per completed tool call)
tail -f ~/Library/Application\ Support/protonmcp/audit.log

# Tail the daemon's slog output
tail -f ~/Library/Logs/protonmcp/daemon.log

Or query the SQLite source of truth for richer analytics:

sqlite3 ~/Library/Application\ Support/protonmcp/store.db \
  'SELECT tool, outcome, policy_decision, duration_ms
     FROM audit_log
    ORDER BY id DESC LIMIT 20;'

Every audit row has: tool name, caller PID + UID + binary, policy decision, outcome (ok / denied / error), approval source (touchid / cached / policy), error message (if any), duration in ms, and redacted args.

Caveats — read before installing

Plaintext bodies on disk (until Phase 8)

When Claude reads a message via mail_read, the decrypted body caches in SQLite for 30 days (protonmcp purge --older-than 7d to shrink the window). On laptop theft + iCloud-restored disk imaging that's recoverable cleartext. The secure_delete=on pragma zeros deleted cells on the next page write; protonmcp purge --vacuum forces it immediately. SQLCipher / envelope encryption is Phase 8.

Proton AppVersion (resolved when Phase 7/E lands)

Today, proto-mcp sends AppVersion: macos-bridge@3.24.2 — Proton Bridge's identifier, not ours. Phase 7/E swaps in a legitimate protonmcp@<version> once Proton grants it (request email is in docs/proton-appversion-request.md). Until then: don't rate-abuse, scrape, or run multi-account automation through proto-mcp. Anything that violates Proton's Terms is no less violating because we're using Bridge's header.

macOS only

internal/keystore uses keybase/go-keychain + cgo against Security.framework. (A SecAccessControl cgo wrapper sits dormant in internal/keystore/access_control_darwin.{h,c,go}, ready to re-enable once Phase 7/E lands the .app bundle + a provisioning profile that authorizes the required keychain-access-groups entitlement.) The Swift helpers need LAContext + AppKit + workspace notifications. Linux builds compile (testing only) but the auth flow won't work.

License

GPLv3. We transitively depend on proton-bridge (also GPLv3) via go-proton-api; that constrains us. See LICENSE.

Testing

For end-to-end validation see TESTING.md — a sectioned playbook another agent (or you) can run to validate build, signing, daemon lifecycle, Touch ID, lock/unlock, per-tool correctness, audit log, and defect regressions. Reports go directly into DEFECTS.html using the existing D-numbering.

For day-to-day development:

make test         # go test ./...
make race         # go test -race ./...
make verify-sign  # codesign --verify each binary (after make sign)

Project status

Phase	Scope	Status
0–2	Build, store, sanitize, sync	Merged
3	MCP server + 9 read tools	Merged
4	Policy + audit + Touch ID + middleware	Merged
5	20 write tools + rate limit + allowed_recipients	Merged
5.5	Security audit follow-up (21 findings closed)	Merged
6	Daemon + shim + launchd + lock/unlock + persistent rate-limit	All sub-PRs in flight
7	Signing, notarization, Keychain ACL, Homebrew, AppVersion	7/A + 7/B + 7/C merged; 7/D reverted (provisioning-profile gap); 7/E in progress
8	SQLCipher / envelope encryption at rest	Planning

TODO.html has the full per-phase plan and the backlog. DEFECTS.html is the truth about what's broken.

Contributing

This is alpha software. PRs welcome but please open an issue first — most architectural direction is locked by the design spec in TODO.html and unsolicited big-scope PRs probably won't land.

.github/CODEOWNERS defines required reviewers for security-load- bearing paths (internal/redact/, internal/keystore/, internal/policy/, internal/approval/, helpers/touchid/, helpers/lockwatch/).

Acknowledgements

• Proton AG for proton-bridge and go-proton-api, on which the entire crypto + transport layer rests. Working on a legitimate AppVersion grant; appreciate the publish of a real Go client.
• Anthropic for the MCP specification and the Claude clients this server targets.
• Every defect in DEFECTS.html that took the shape it did because someone — cmd-r, claude-review, claude-security-review, or a live testing session — looked at the same code more carefully than I would have on my own.