{"_id":"@alpharomercoma/proton-bridge-mcp","_rev":"6-986ef12dd4b15e8e423706fc20cf10be","name":"@alpharomercoma/proton-bridge-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@alpharomercoma/proton-bridge-mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","proton-mail","proton-bridge","imap","claude","email"],"author":"","license":"MIT","_id":"@alpharomercoma/proton-bridge-mcp@1.0.0","maintainers":[{"name":"alpharomercoma","email":"alpharomercoma@proton.me"}],"homepage":"https://github.com/alpharomercoma/proton-bridge-mcp#readme","bugs":{"url":"https://github.com/alpharomercoma/proton-bridge-mcp/issues"},"bin":{"proton-bridge-mcp":"bin/proton-bridge-mcp.mjs","proton-bridge-mcp-setup":"bin/setup.mjs"},"dist":{"shasum":"781a6d205759709d7a8d56dfce4b90fb02abc267","tarball":"https://registry.npmjs.org/@alpharomercoma/proton-bridge-mcp/-/proton-bridge-mcp-1.0.0.tgz","fileCount":6,"integrity":"sha512-jpGID392blWrz/iBmoMgWSprPwxfDsrVXTsEUvZb1REAzdByiS30YSMFIV7AugtejDYuUHBLieyPJR5Es5wxOw==","signatures":[{"sig":"MEUCIQCvO4RLCJ/n2EA6/2AVGUqsH7+LiRIuSWWm0VR9vYNrgwIgFll3cvAreGEYa23NoLovmdhCcge4i23dgIxRuspPp4k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24019},"type":"module","engines":{"node":">=18"},"gitHead":"b63f8e42bfb38b188e7c3619a968c3c472aa84eb","scripts":{"check":"node --check src/server.js && node --check bin/proton-bridge-mcp.mjs && node --check bin/setup.mjs","setup":"node bin/setup.mjs","start":"node bin/proton-bridge-mcp.mjs"},"_npmUser":{"name":"alpharomercoma","email":"alpharomercoma@proton.me"},"repository":{"url":"git+https://github.com/alpharomercoma/proton-bridge-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"MCP server for reading and searching Proton Mail via Proton Mail Bridge (IMAP), with certificate pinning instead of disabled TLS verification.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.24.0","imapflow":"^1.0.184","mailparser":"^3.7.2","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/proton-bridge-mcp_1.0.0_1785873579578_0.27074202993754515","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@alpharomercoma/proton-bridge-mcp","version":"1.0.1","keywords":["mcp","model-context-protocol","proton-mail","proton-bridge","imap","claude","email"],"author":"","license":"MIT","_id":"@alpharomercoma/proton-bridge-mcp@1.0.1","maintainers":[{"name":"alpharomercoma","email":"alpharomercoma@proton.me"}],"homepage":"https://github.com/alpharomercoma/proton-bridge-mcp#readme","bugs":{"url":"https://github.com/alpharomercoma/proton-bridge-mcp/issues"},"bin":{"proton-bridge-mcp":"bin/proton-bridge-mcp.mjs","proton-bridge-mcp-setup":"bin/setup.mjs"},"dist":{"shasum":"a356dec29fa7433216f99e822040201035cd3b5e","tarball":"https://registry.npmjs.org/@alpharomercoma/proton-bridge-mcp/-/proton-bridge-mcp-1.0.1.tgz","fileCount":6,"integrity":"sha512-uOjjrR7ytmgKzvsqqIJ5b5qocjDNolQVUqjsx4MrK6zmLNyoibHrLGPbqJUEDVrphc9WMg/pNp67trnuAHS57Q==","signatures":[{"sig":"MEYCIQD7QtsdQGcwfBeUzf6CwPwtdx/uPoX3tUqFQKuPl66r3QIhAOTUYiMYXJwzE/E+twoJm4a3UylAftkihkJd8Uw+lrQK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24966},"type":"module","engines":{"node":">=18"},"gitHead":"1309a1e08f53fc842227c8af801e7a05c2e23135","scripts":{"check":"node --input-type=module -e \"await Promise.all(['./src/server.js','./bin/proton-bridge-mcp.mjs','./bin/setup.mjs'].map(f=>import(f)))\"","setup":"node bin/setup.mjs","start":"node bin/proton-bridge-mcp.mjs"},"_npmUser":{"name":"alpharomercoma","email":"alpharomercoma@proton.me"},"repository":{"url":"git+https://github.com/alpharomercoma/proton-bridge-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"MCP server for reading and searching Proton Mail via Proton Mail Bridge (IMAP), with certificate pinning instead of disabled TLS verification.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.24.0","imapflow":"^1.0.184","mailparser":"^3.7.2","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/proton-bridge-mcp_1.0.1_1785901934922_0.7026791814290623","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@alpharomercoma/proton-bridge-mcp","version":"1.0.2","keywords":["mcp","model-context-protocol","proton-mail","proton-bridge","imap","claude","email"],"author":"","license":"MIT","_id":"@alpharomercoma/proton-bridge-mcp@1.0.2","maintainers":[{"name":"alpharomercoma","email":"alpharomercoma@proton.me"}],"homepage":"https://github.com/alpharomercoma/proton-bridge-mcp#readme","bugs":{"url":"https://github.com/alpharomercoma/proton-bridge-mcp/issues"},"bin":{"proton-bridge-mcp":"bin/proton-bridge-mcp.mjs","proton-bridge-mcp-setup":"bin/setup.mjs"},"dist":{"shasum":"6d37535816ecc24bb8e201deea2aabd4bbe1054b","tarball":"https://registry.npmjs.org/@alpharomercoma/proton-bridge-mcp/-/proton-bridge-mcp-1.0.2.tgz","fileCount":6,"integrity":"sha512-5GzbbZGwS/ViAIrc5DjyiUsQ7HTdnd8tHO0xTReVwkh3ebg0/cvWgKJmP+QE+ftLx88qdrujwjAyffJm6nVHkA==","signatures":[{"sig":"MEUCIH4oB8IXQ5ZAnWaM9bgmNmOM52/XlOqv0huGUG0V5V7oAiEAvHy3RK2YUqE0rHZdIa7cC31QNvx6/q5GB0BvVHJV1Bo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25954},"type":"module","engines":{"node":">=18"},"gitHead":"d2fa802adc100d47e084e3569f96f66f36d9ab80","scripts":{"check":"node --input-type=module -e \"await Promise.all(['./src/server.js','./bin/proton-bridge-mcp.mjs','./bin/setup.mjs'].map(f=>import(f)))\"","setup":"node bin/setup.mjs","start":"node bin/proton-bridge-mcp.mjs"},"_npmUser":{"name":"alpharomercoma","email":"alpharomercoma@proton.me"},"repository":{"url":"git+https://github.com/alpharomercoma/proton-bridge-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"MCP server for reading and searching Proton Mail via Proton Mail Bridge (IMAP), with certificate pinning instead of disabled TLS verification.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.24.0","imapflow":"^1.0.184","mailparser":"^3.7.2","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/proton-bridge-mcp_1.0.2_1785902588083_0.42404823790275636","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@alpharomercoma/proton-bridge-mcp","version":"1.0.3","keywords":["mcp","model-context-protocol","proton-mail","proton-bridge","imap","claude","email"],"author":"","license":"MIT","_id":"@alpharomercoma/proton-bridge-mcp@1.0.3","maintainers":[{"name":"alpharomercoma","email":"alpharomercoma@proton.me"}],"homepage":"https://github.com/alpharomercoma/proton-bridge-mcp#readme","bugs":{"url":"https://github.com/alpharomercoma/proton-bridge-mcp/issues"},"bin":{"proton-bridge-mcp":"bin/proton-bridge-mcp.mjs","proton-bridge-mcp-setup":"bin/setup.mjs"},"dist":{"shasum":"8a310722fea516da27aa853c0604cbb95b195271","tarball":"https://registry.npmjs.org/@alpharomercoma/proton-bridge-mcp/-/proton-bridge-mcp-1.0.3.tgz","fileCount":6,"integrity":"sha512-j+WTYvR60erY7Hfr4MyMDvrAZY8BxRM/Zp6cRVihKQb0eD/HkUm8413k+7Sg0lRRRlvC2sUzXKDxBuW+MmI9+A==","signatures":[{"sig":"MEQCIAfnI3PDpRx0spIWDCanfrGF4wIagA7+ZTZSaYqXoS4IAiBJdLU5K3BGVUZzYKV3hOfIkbtOLD1ez1kOztPTOK1aaA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26210},"type":"module","engines":{"node":">=18"},"gitHead":"34481e96f1bdc1a27cacb9c77ced5362e74802c2","scripts":{"check":"node --input-type=module -e \"await Promise.all(['./src/server.js','./bin/proton-bridge-mcp.mjs','./bin/setup.mjs'].map(f=>import(f)))\"","setup":"node bin/setup.mjs","start":"node bin/proton-bridge-mcp.mjs"},"_npmUser":{"name":"alpharomercoma","email":"alpharomercoma@proton.me"},"repository":{"url":"git+https://github.com/alpharomercoma/proton-bridge-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"MCP server for reading and searching Proton Mail via Proton Mail Bridge (IMAP), with certificate pinning instead of disabled TLS verification.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.24.0","imapflow":"^1.0.184","mailparser":"^3.7.2","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/proton-bridge-mcp_1.0.3_1785905282541_0.9462400017054629","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@alpharomercoma/proton-bridge-mcp","version":"1.0.4","keywords":["mcp","model-context-protocol","proton-mail","proton-bridge","imap","claude","email"],"author":"","license":"MIT","_id":"@alpharomercoma/proton-bridge-mcp@1.0.4","maintainers":[{"name":"alpharomercoma","email":"alpharomercoma@proton.me"}],"homepage":"https://github.com/alpharomercoma/proton-bridge-mcp#readme","bugs":{"url":"https://github.com/alpharomercoma/proton-bridge-mcp/issues"},"bin":{"proton-bridge-mcp":"bin/proton-bridge-mcp.mjs","proton-bridge-mcp-setup":"bin/setup.mjs"},"dist":{"shasum":"8659e7e4baf794e27e4e612e5d95b27219ed7eb8","tarball":"https://registry.npmjs.org/@alpharomercoma/proton-bridge-mcp/-/proton-bridge-mcp-1.0.4.tgz","fileCount":6,"integrity":"sha512-cSW2jiEKMhBxTNZj8YF5Llk1s5PQiL/k7yCIjQFBeG/Zk0i+AXnlc3A5ijSM3Q0CyWkeSq/auSm6cXJZv3QLXw==","signatures":[{"sig":"MEQCIHLdnMYKmM5afYrwLzQWf8AhFcuDLApKJc0EMohOlqkiAiAPXiHSuDTTELXINctGS4BvTwyRsnC/GJxAjZHbPwk8Kw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27502},"type":"module","engines":{"node":">=18"},"gitHead":"e54a218f6f564b697b947f0dddb5311d46462ea4","scripts":{"check":"node --input-type=module -e \"await Promise.all(['./src/server.js','./bin/proton-bridge-mcp.mjs','./bin/setup.mjs'].map(f=>import(f)))\"","setup":"node bin/setup.mjs","start":"node bin/proton-bridge-mcp.mjs"},"_npmUser":{"name":"alpharomercoma","email":"alpharomercoma@proton.me"},"repository":{"url":"git+https://github.com/alpharomercoma/proton-bridge-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"MCP server for reading and searching Proton Mail via Proton Mail Bridge (IMAP), with certificate pinning instead of disabled TLS verification.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.24.0","imapflow":"^1.0.184","mailparser":"^3.7.2","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/proton-bridge-mcp_1.0.4_1785905925375_0.8293749928770198","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@alpharomercoma/proton-bridge-mcp","version":"1.1.0","publishConfig":{"access":"public"},"description":"MCP server for reading, searching, organizing, and sending Proton Mail via Proton Mail Bridge (IMAP/SMTP), with certificate pinning instead of disabled TLS verification.","type":"module","license":"MIT","author":"","homepage":"https://github.com/alpharomercoma/proton-bridge-mcp#readme","repository":{"type":"git","url":"git+https://github.com/alpharomercoma/proton-bridge-mcp.git"},"bugs":{"url":"https://github.com/alpharomercoma/proton-bridge-mcp/issues"},"keywords":["mcp","model-context-protocol","proton-mail","proton-bridge","imap","claude","email"],"engines":{"node":">=18"},"bin":{"proton-bridge-mcp":"bin/proton-bridge-mcp.mjs","proton-bridge-mcp-setup":"bin/setup.mjs"},"scripts":{"start":"node bin/proton-bridge-mcp.mjs","setup":"node bin/setup.mjs","check":"node --input-type=module -e \"await Promise.all(['./src/server.js','./bin/proton-bridge-mcp.mjs','./bin/setup.mjs'].map(f=>import(f)))\"","test":"node --test test/*.test.js","lint":"eslint .","build":"npm run check && npm pack --dry-run"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","imapflow":"^1.0.184","mailparser":"^3.7.2","nodemailer":"^9.1.1","zod":"^3.24.0"},"devDependencies":{"@eslint/js":"^10.0.1","eslint":"^10.10.0","globals":"^17.12.0"},"gitHead":"8daf45a3529ae78e93cf8ec4e283604f8f8eec30","_id":"@alpharomercoma/proton-bridge-mcp@1.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-pJfKbHKJVtTXpj2Pj3X8VTFDRtrEn9lYrHrrpJXp1gZgZrMpRCuh+IxdMMJWikSBEV+XqGr+WCioAFuncYnxyw==","shasum":"84d408b9c8c87cd6c885cc00e84ebd83cd6ad2ec","tarball":"https://registry.npmjs.org/@alpharomercoma/proton-bridge-mcp/-/proton-bridge-mcp-1.1.0.tgz","fileCount":6,"unpackedSize":50019,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIE/Ge0logxwy8Hu0HKfQbbqCmlJNIiWlsemk9dgPmt4iAiAw6TPSBTBhmCX8/gHMgM51UcehwCDVne2Okats3ybBjQ=="}]},"_npmUser":{"name":"alpharomercoma","email":"alpharomercoma@proton.me"},"directories":{},"maintainers":[{"name":"alpharomercoma","email":"alpharomercoma@proton.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/proton-bridge-mcp_1.1.0_1788617826683_0.05469930944931356"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-04T19:59:39.338Z","modified":"2026-09-05T14:17:06.963Z","1.0.0":"2026-08-04T19:59:39.710Z","1.0.1":"2026-08-05T03:52:15.068Z","1.0.2":"2026-08-05T04:03:08.226Z","1.0.3":"2026-08-05T04:48:02.698Z","1.0.4":"2026-08-05T04:58:45.505Z","1.1.0":"2026-09-05T14:17:06.816Z"},"bugs":{"url":"https://github.com/alpharomercoma/proton-bridge-mcp/issues"},"license":"MIT","homepage":"https://github.com/alpharomercoma/proton-bridge-mcp#readme","keywords":["mcp","model-context-protocol","proton-mail","proton-bridge","imap","claude","email"],"repository":{"type":"git","url":"git+https://github.com/alpharomercoma/proton-bridge-mcp.git"},"description":"MCP server for reading, searching, organizing, and sending Proton Mail via Proton Mail Bridge (IMAP/SMTP), with certificate pinning instead of disabled TLS verification.","maintainers":[{"name":"alpharomercoma","email":"alpharomercoma@proton.me"}],"readme":"# proton-bridge-mcp\n\nAn [MCP](https://modelcontextprotocol.io) server that lets AI assistants (Claude Code, Claude Desktop, and other MCP clients) read, search, organize, and send Proton Mail through [Proton Mail Bridge](https://proton.me/mail/bridge).\n\nUnofficial, community project. Not affiliated with or endorsed by Proton AG.\n\n## Why Bridge, and why this exists\n\nProton Mail doesn't expose a public IMAP/SMTP API directly — Proton Mail Bridge runs locally, decrypts your mail, and re-exposes it as standard IMAP/SMTP on `127.0.0.1`. That's the only supported way to speak IMAP to a Proton Mail account programmatically.\n\nBridge's local IMAP/SMTP listener uses a **self-signed TLS certificate** generated per install. Most quick-start IMAP MCP servers handle this by disabling certificate verification (`rejectUnauthorized: false`) — which defeats the purpose of TLS. This server instead **pins the exact certificate** Bridge presents at setup time and validates every connection against it, so a certificate swap (e.g. from another process impersonating Bridge on your machine) is still detected and rejected.\n\n## Features\n\n- `list_mailboxes` — list all folders/labels\n- `list_messages` — list recent messages in a mailbox\n- `search_messages` — search by sender, subject, or body text\n- `get_message` — fetch headers, plain-text body, flags, and attachment metadata for a message by UID (does not mark it read). All read tools label returned mail as untrusted data, since a hostile email could try to instruct the model\n- `move_messages` — move messages to another mailbox: trash, archive, restore to inbox, mark as spam, or file into any folder\n- `flag_messages` — star/unstar or mark read/unread\n- `delete_messages` — permanently delete (expunge); irreversible in Trash/Spam/Drafts, elsewhere Bridge turns it into a move to Trash\n- `manage_mailbox` — create, rename, or delete a folder (`Folders/...`) or label (`Labels/...`)\n- `send_message` — send an email via Bridge SMTP, optionally as a threaded reply to a UID\n- `create_draft` — compose the same way but save to Drafts instead of sending\n\nThe first four tools are read-only and carry `readOnlyHint`. The rest modify your mailbox or send mail and are annotated as writes (`readOnlyHint: false`, plus `destructiveHint` on everything except `send_message` and `create_draft`, since clearing a flag or moving/deleting mail undoes existing state), so MCP clients that gate on annotations will prompt before running them.\n\nEvery `mailbox` argument (and `move_messages`'s `destination`, and `reply_mailbox`) accepts either an alias (`inbox`, `trash`, `archive`, `spam`, `sent`, `drafts`) or an exact mailbox path from `list_mailboxes`. Aliases resolve through the IMAP special-use attributes Bridge advertises (`\\Trash`, `\\Archive`, ...), with a fallback to the conventional folder name. `flag_messages` takes `flag: \"starred\" | \"read\"` and a boolean `value`; Proton's star is the IMAP `\\Flagged` flag. `move_messages`, `flag_messages`, and `delete_messages` accept a list of up to 100 UIDs (from `list_messages` or `search_messages`), so you can act on many messages in one call.\n\n`send_message` and `create_draft` take `to`/`cc`/`bcc` (string or array), `subject`, `text`, and optional `html`. A recipient is required to send but optional for a draft. Pass `reply_to_uid` (and `reply_mailbox` if not INBOX) to reply: the recipient defaults to the original's Reply-To/From, the subject to `Re: ...`, and `In-Reply-To`/`References` are set so the reply threads correctly. Sending goes through Bridge's SMTP listener (default port `1025`, STARTTLS) validated against the same pinned certificate as IMAP.\n\n## Prerequisites\n\n- A Proton Mail plan that supports Bridge (Unlimited, Business, or legacy Professional/Visionary — Bridge requires a paid plan)\n- [Proton Mail Bridge](https://proton.me/mail/bridge) installed, running, and logged in\n- Node.js 18+\n- An MCP client: [Claude Code](https://claude.com/claude-code), Claude Desktop, or any other MCP-compatible client\n\n## Setup\n\n### 1. Install\n\n```bash\ngit clone https://github.com/alpharomercoma/proton-bridge-mcp.git\ncd proton-bridge-mcp\nnpm install\n```\n\n(Once published to npm, this step will be optional — see [Using via npx](#using-via-npx) below.)\n\n### 2. Run the setup wizard\n\n```bash\nnpm run setup\n```\n\nYou'll be asked for:\n\n- Bridge IMAP host/port (defaults: `127.0.0.1` / `1143`) and SMTP port (default `1025`)\n- Your Proton Mail address\n- Your **Bridge password** — this is a Bridge-generated password shown in the Bridge app under your account, *not* your normal Proton account password\n\nThe wizard then:\n\n1. Connects to Bridge and performs the real IMAP `STARTTLS` upgrade to fetch its certificate (no `openssl` dependency — a portable Node-native handshake)\n2. Prints the certificate's SHA-256 fingerprint for your own awareness\n3. Verifies login actually works, validated strictly against that same pinned certificate\n4. Writes `~/.config/proton-bridge-mcp/credentials.json` and `bridge-ca.pem`, both `chmod 600`, inside a `chmod 700` directory\n\nNothing is written until login has been verified.\n\n### 3. Register with your MCP client\n\n**Claude Code:**\n\n```bash\nclaude mcp add proton-mail -s user -- node /path/to/proton-bridge-mcp/bin/proton-bridge-mcp.mjs\n```\n\n(Use `-- npx -y @alpharomercoma/proton-bridge-mcp` instead — see [Using via npx](#using-via-npx) below.)\n\n**Claude Desktop / other MCP clients** — add to your MCP config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"proton-mail\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/proton-bridge-mcp/bin/proton-bridge-mcp.mjs\"]\n    }\n  }\n}\n```\n\n### Using via npx\n\nPublished on npm as [`@alpharomercoma/proton-bridge-mcp`](https://www.npmjs.com/package/@alpharomercoma/proton-bridge-mcp) — skip the local clone entirely:\n\n```bash\nnpx -y -p @alpharomercoma/proton-bridge-mcp proton-bridge-mcp-setup\nclaude mcp add proton-mail -s user -- npx -y @alpharomercoma/proton-bridge-mcp\n```\n\n**Codex CLI:**\n\nTested end-to-end against Codex CLI 0.146.0 (`codex mcp add`, real Bridge connection, real tool calls). Two things are Codex-specific and easy to miss:\n\n1. Codex's MCP support is behind an under-development feature flag as of 0.146.0. Enable it once:\n\n   ```bash\n   codex features enable mcp_2026_07_28\n   ```\n\n2. Register the server with an **exact, pinned version** — not a bare `npx -y @alpharomercoma/proton-bridge-mcp`:\n\n   ```bash\n   codex mcp add proton-mail -- npx -y @alpharomercoma/proton-bridge-mcp@1.1.0\n   ```\n\n   Reason: if you've ever run `npm install -g @alpharomercoma/proton-bridge-mcp` on the same machine, an unpinned `npx` invocation will silently prefer that stale global install over fetching the current version from the registry — no error, it just quietly runs old code. Pinning the version sidesteps this entirely. Bump the pinned version here when you upgrade.\n\nOnce registered, `codex mcp get proton-mail` should show `enabled: true`, and the read-only tools (`list_mailboxes`, `list_messages`, `search_messages`, `get_message`) work in both the interactive `codex` session and non-interactive `codex exec` runs without triggering an approval prompt — they're tagged with `readOnlyHint` annotations for exactly this reason. The write tools (everything after `get_message`) are not read-only, so expect an approval prompt for those depending on your client's policy.\n\n## Configuration reference\n\nBy default, config lives at `~/.config/proton-bridge-mcp/`. Override the location or individual values with environment variables (useful for multiple accounts or containers):\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `PROTON_BRIDGE_MCP_HOME` | Config directory | `~/.config/proton-bridge-mcp` |\n| `PROTON_BRIDGE_HOST` | Bridge IMAP/SMTP host | value from `credentials.json` |\n| `PROTON_BRIDGE_PORT` | Bridge IMAP port | value from `credentials.json` (default `1143`) |\n| `PROTON_BRIDGE_SMTP_PORT` | Bridge SMTP port (sending) | value from `credentials.json` (default `1025`) |\n| `PROTON_BRIDGE_USER` | Proton Mail address | value from `credentials.json` |\n| `PROTON_BRIDGE_PASSWORD` | Bridge password | value from `credentials.json` |\n| `PROTON_BRIDGE_CA_PATH` | Path to pinned cert PEM | `<config dir>/bridge-ca.pem` |\n\nEnvironment variables always take precedence over the credentials file.\n\n## Security model\n\n- **No disabled TLS verification.** The server validates every connection against the certificate pinned during setup (`tls.ca`), not `rejectUnauthorized: false`.\n- **Trust-on-first-use, like SSH.** The one moment we can't validate against anything is fetching the certificate itself during setup — the same bootstrap problem SSH solves by showing you a host-key fingerprint on first connect. Bridge only listens on `127.0.0.1`, so this step can't be intercepted over the network; only another process already running as you on the same machine could tamper with it, and at that point your credentials file is equally exposed regardless of TLS.\n- **Credentials never touch the MCP client's own config.** Rather than passing `-e PROTON_BRIDGE_PASSWORD=...` to `claude mcp add` (which lands in `~/.claude.json` and your shell history), the password lives only in `credentials.json`, `chmod 600`, outside any repo or synced config.\n- **Rotate the Bridge password if it's ever been pasted into a chat, terminal share, or committed by accident.** Bridge passwords are cheap to regenerate (Bridge app → account → \"Generate new password\") and don't touch your actual Proton account password.\n\n## Troubleshooting\n\n**`Missing Proton Bridge \"host\"` / `\"user\"` / `\"password\"`** — run `npm run setup` (or `npx -p @alpharomercoma/proton-bridge-mcp proton-bridge-mcp-setup`) first, or set the `PROTON_BRIDGE_*` env vars.\n\n**`No pinned Bridge certificate found`** — same as above; the setup wizard writes `bridge-ca.pem` alongside the credentials.\n\n**Login fails during setup** — double check you're using the Bridge-generated password (visible in the Bridge app), not your Proton account password. Also confirm Bridge is running and unlocked.\n\n**Certificate fingerprint changes unexpectedly** — this happens if you reinstall Bridge or reset its config (it regenerates its cert). Re-run `npm run setup` to re-pin. If you didn't reinstall Bridge and the fingerprint changed anyway, treat that as suspicious and investigate before continuing.\n\n## Contributing\n\nIssues and PRs welcome. Run `npm run lint`, `npm test`, and `npm run build` (syntax check plus a dry-run `npm pack`) before opening a PR; CI runs the same three on Node 18/20/22. Keep changes scoped. Anything that widens what the server can do to your mailbox (new write tools, attachments, bulk operations) should come with tests and a README note on its safety annotations.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}