Comlink
Provides full Proton Mail mailbox capability through Proton Mail Bridge's local IMAP/SMTP endpoints, including reading, searching, triaging, organizing, drafting, and gated sending of messages.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Comlink
Comlink is a Proton Mail MCP server. It gives Claude full mailbox capability —
read, search, triage, organize, draft, and (gated) send — by talking to Proton Mail
Bridge's local IMAP/SMTP endpoints. Bridge handles all encryption/decryption and
server sync; Comlink is a thin, well-typed protocol adapter with strong safety rails on
anything that leaves the machine. The server registers its tools under the proton_
prefix (server name proton_mail_mcp).
Phase 1 (this README): local stdio. Comlink runs as a subprocess of Claude Desktop /
Claude Code on your Mac and reaches Bridge over 127.0.0.1. Zero networking, no inbound
ports.
Phase 2 (deferred, design only): remote. A streamable-http deployment on Gonk K3s,
exposed as a public HTTPS endpoint behind OAuth so the Claude mobile app / claude.ai
can reach it (a tailnet cannot). The transport and OAuth token validation are not yet
implemented. See docs/design-doc.md §2 and Epic 5 for the threat model.
1. Prerequisites
macOS with Homebrew.
uv—brew install uv.Proton Mail Bridge, installed and logged in. Comlink never sees your Proton account password; it uses the Bridge-generated app password. Bridge must be running whenever Comlink is used.
Claude Desktop and/or Claude Code.
Clone and sync the project:
git clone <your-fork-or-origin> ~/dev/comlink
cd ~/dev/comlink
uv syncTarget: a working setup on a fresh Mac in under 15 minutes.
Related MCP server: proton-mail-mcp
2. Proton Mail Bridge: install and get the app password
Install Bridge —
brew install --cask proton-mail-bridge(or download from Proton) — and sign in with your Proton account. Leave it running.In Bridge, open Mailbox details for your account. It shows:
the IMAP host/port (
127.0.0.1:1143, STARTTLS),the SMTP host/port (
127.0.0.1:1025, STARTTLS),the username (usually your Proton email address),
the app password — a Bridge-generated password, not your Proton login password.
Copy the app password. You'll store it in the Keychain next.
If the app password ever rotates (re-login, reconfigure), repeat the Keychain step below.
3. Store the Bridge app password (macOS Keychain)
Don't put the password in plaintext config. Store it in the Keychain once:
security add-generic-password -s proton-bridge -a "$USER" -w
# (you'll be prompted to paste the Bridge app password; -w with no value reads it interactively)Comlink retrieves it at runtime via a shell command (COMLINK_PASSWORD_COMMAND). The exact
retrieval command — the one you put in config — is:
security find-generic-password -s proton-bridge -wThat prints the password to stdout; Comlink reads stdout (stripped) and never logs it.
Vaultwarden alternative. If you keep the Bridge password in your self-hosted Vaultwarden
via the Bitwarden CLI, use this as COMLINK_PASSWORD_COMMAND instead (unlock bw first):
bw get password proton-bridge4. Configuration (COMLINK_* environment variables)
All configuration is environment variables with the COMLINK_ prefix. Secrets are never
logged. Mirrors src/comlink/config.py.
Variable | Default | Notes |
|
| Bridge IMAP host |
|
| Bridge IMAP port (STARTTLS) |
|
| Bridge SMTP host |
|
| Bridge SMTP port. |
|
|
|
|
| Bridge username (usually your Proton address) |
| unset | Bridge app password (NOT the Proton account password). Prefer the command form below. |
| unset | Shell command whose stdout is the app password, e.g. |
|
|
|
| unset | Pinned Bridge certificate for |
|
| When |
|
| Master send gate. When |
|
| Comma-separated recipients. Exact address ( |
|
| Sliding-window send rate limit. |
|
| Append-only JSONL of every send and delete. |
|
|
|
|
| Bind address for |
|
| Bind port for |
|
| Mount path for the |
|
| Comma-separated |
|
| Defense-in-depth gate for |
|
| Cloudflare Access application AUD tag (an identifier, not a secret). Required when the gate is on. |
|
| Cloudflare Access team domain, e.g. |
|
| Comma-separated allowlist of |
Set at least COMLINK_USERNAME and COMLINK_PASSWORD_COMMAND. Everything else has working
defaults for a local Bridge.
5. Register the server with your MCP client
Comlink installs a console entry point named comlink (comlink = "comlink.server:main"
in pyproject.toml), which uv run invokes.
Claude Desktop (claude_desktop_config.json) / Claude Code (.mcp.json)
{
"mcpServers": {
"comlink": {
"command": "uv",
"args": ["run", "--directory", "/Users/brandon/dev/comlink", "comlink"],
"env": {
"COMLINK_USERNAME": "you@proton.me",
"COMLINK_PASSWORD_COMMAND": "security find-generic-password -s proton-bridge -w",
"COMLINK_ALLOW_SEND": "false"
}
}
}
}Adjust --directory to where you cloned the repo and COMLINK_USERNAME to your Bridge
username. Restart Claude Desktop (or reload the MCP config in Claude Code) to pick it up.
To run it by hand for debugging:
COMLINK_USERNAME=you@proton.me \
COMLINK_PASSWORD_COMMAND="security find-generic-password -s proton-bridge -w" \
uv run --directory ~/dev/comlink comlink6. Smoke test (health check)
With Bridge running and the server registered, ask Claude to run the proton_health_check
tool (or invoke it from the MCP Inspector). It verifies IMAP + SMTP connectivity and reports:
Bridge reachability,
the account (
COMLINK_USERNAME),folder count,
send-gate status: enabled/disabled, allowlist size, max-per-hour, and remaining hourly budget.
Inspector pass over every tool:
npx @modelcontextprotocol/inspector uv run --directory ~/dev/comlink comlinkIf health check reports the Bridge unreachable, start the Bridge app and retry. If IMAP login is rejected, the app password likely rotated — re-run the Keychain step in §3.
7. The send gate (read before enabling send)
proton_send_message is the only tool that puts mail on the wire, and it is gated in three
structural layers:
Env flag (registration).
COMLINK_ALLOW_SENDmust betrue. When it isfalse,proton_send_messageis not registered at all — it is invisible to the client, not a tool that exists and refuses. This is the default. The draft path (proton_save_draft) is always available; prefer it.Recipient allowlist. With send enabled, every recipient must match
COMLINK_SEND_ALLOWLIST(exact address or*@domain). A non-matching recipient is rejected by name. An empty allowlist means any-recipient mode and is warned about loudly at startup — set the allowlist.Confirm + rate limit. The call must assert
confirm: true(schema-required), and sends are capped atCOMLINK_SEND_MAX_PER_HOUR(default 5) on a sliding window. Every send is written to the audit log.
To enable send, set COMLINK_ALLOW_SEND=true and a non-empty COMLINK_SEND_ALLOWLIST:
"env": {
"COMLINK_USERNAME": "you@proton.me",
"COMLINK_PASSWORD_COMMAND": "security find-generic-password -s proton-bridge -w",
"COMLINK_ALLOW_SEND": "true",
"COMLINK_SEND_ALLOWLIST": "alice@chaosbit.dev, *@chaosbit.dev"
}Why the gate defaults off. Email content is attacker-controlled. A hostile message read into the model's context is a prompt-injection vector aimed at your send/move/delete tools. The gate exists to bound the blast radius: with it off, no amount of injected text can make Comlink emit mail, because the tool isn't there. Security posture is the feature — leave send off unless you have a specific reason, and keep the allowlist tight when you turn it on.
8. Security note
Email content is untrusted input. Message bodies and summary fields (subjects, sender and recipient names) are returned to the model with an untrusted-content marker. That marker is advisory — it biases the model, it is not an enforcement boundary.
The structural gate is the real defense. Send is bounded by env flag → allowlist → confirm → rate limit. Deletes are soft: messages move to Trash, never EXPUNGE; deleting from Trash or Spam is refused (empty those from a Proton client).
Credentials. Prefer
COMLINK_PASSWORD_COMMAND(Keychain / Vaultwarden) over a static password. The password is never logged and is scrubbed from surfaced error text.Audit trail. Every send and delete appends a line to
COMLINK_AUDIT_LOG(~/.comlink/audit.jsonlby default) with enough detail to reconstruct what an agent did.
9. Troubleshooting
Symptom | Likely cause | Fix |
| Bridge app not running | Start Proton Mail Bridge and retry. |
| Bridge app password rotated | Re-run §3 Keychain store with the new app password from Bridge → Mailbox details. |
| Misspelled folder name | Use |
| Tried to move into a label | Labels coexist with folders in Proton; move into a folder, or apply labels from a Proton client. |
| Send gate / allowlist / rate limit | The message names which layer; adjust |
| Cached UIDs went stale | Re-run |
|
| Intentional — set it to |
Error classes match the design doc §8 taxonomy; every message tells the agent what to do next.
10. References
Design doc:
docs/design-doc.md(architecture, Bridge constraints, security model, epics).MCP spec: https://modelcontextprotocol.io
Proton Mail Bridge: https://proton.me/mail/bridge
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Bring Gmail, Outlook, iCloud Mail, Yahoo Mail, Fastmail and other IMAP mailboxes together. Search connected email, including semantic search; cached or indexed results may be incomplete or stale. Read messages and attachments, create drafts, send or reply when requested, and manage rules for new mail. Separate permissions control reading, attachments, drafts, sending and mailbox changes.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Search and triage all your mailboxes; draft replies and campaigns; send only as you allow.
Never-stored live email: read, send and triage Gmail, Outlook / Microsoft 365, or any IMAP mailbox.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI assistants to read, organize, and send Proton Mail through the local Proton Bridge, with careful gating for sending and attachment access.252Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with a Proton Mail mailbox through Proton Bridge, supporting listing, searching, reading, sending, and organizing emails.-
- AlicenseBqualityBmaintenanceEnables AI assistants to read, search, send, reply, and organize ProtonMail emails through a local ProtonMail Bridge, with automatic Bridge discovery and pinned TLS verification.23LGPL 3.0
- AlicenseAqualityBmaintenanceEnables AI agents to read a Proton Mail mailbox through a local Proton Bridge instance, listing folders, browsing recent messages, running full-text searches, and reading individual messages with decoded bodies and attachment info. All access is read-only — mailboxes are opened in IMAP READONLY mode, so nothing is ever modified, and the capability model lets operators opt into future draft, organize, send, and delete tools behind explicit confirmations.10180 PyPIMIT