Troubleshooting
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| Tool error: "Proton Pass session expired" | Run pass-cli login in your terminal, then retry. The server does not need a restart. |
| pass-cli "hangs" / times out | There is almost certainly a hidden macOS Keychain dialog waiting for you (check your other desktop/monitor). Enter your Mac login password and click Always Allow. |
| "Connection refused" on port 1143/1025 | Bridge isn't running. Open Proton Mail Bridge and make sure your account shows as connected. |
| A just-sent email isn't found by subject search | Bridge indexes fresh messages with a small delay; retry shortly, or search the folder without a subject filter. |
| Send tools missing | PROTONMCP_ALLOW_SEND isn't true, or PROTONMCP_READ_ONLY is true — that's the configuration working as intended. |
| Sends refused with "client does not support elicitation" | Your MCP client can't render approval prompts. Draft instead and send from the Proton app, or use a client with elicitation support (e.g. Claude Code). |
| "pass-cli not found" | Install it (brew install protonpass/tap/pass-cli). If it's installed somewhere unusual, set PROTONMCP_PASS_CLI=/path/to/pass-cli in the registration. Check what the server resolved with the runtime_status tool. |
Note on Python 3.14: imapclient 3.1.0 is incompatible with Python
3.14's imaplib (read-only file property). This server ships a small,
version-tolerant compatibility shim in src/mcp_proton_email/imap.py — no
action needed, documented so future upgrades can drop it.