Skip to main content
Glama
Comlink

Comlink

by chaosbit-dev

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 sync

Target: 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

  1. Install Bridge — brew install --cask proton-mail-bridge (or download from Proton) — and sign in with your Proton account. Leave it running.

  2. 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.

  3. 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 -w

That 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-bridge

4. 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

COMLINK_IMAP_HOST

127.0.0.1

Bridge IMAP host

COMLINK_IMAP_PORT

1143

Bridge IMAP port (STARTTLS)

COMLINK_SMTP_HOST

127.0.0.1

Bridge SMTP host

COMLINK_SMTP_PORT

1025

Bridge SMTP port.

COMLINK_SMTP_SECURITY

starttls

starttls (connect plaintext, upgrade in-band — Bridge default) or ssl (implicit TLS on connect). Set to ssl if your Bridge's SMTP is configured for SSL/TLS.

COMLINK_USERNAME

""

Bridge username (usually your Proton address)

COMLINK_PASSWORD

unset

Bridge app password (NOT the Proton account password). Prefer the command form below.

COMLINK_PASSWORD_COMMAND

unset

Shell command whose stdout is the app password, e.g. security find-generic-password -s proton-bridge -w (Keychain) or bw get password proton-bridge (Vaultwarden). Wins over COMLINK_PASSWORD if both are set.

COMLINK_TLS_MODE

verify

verify or no-verify. no-verify is refused for non-localhost hosts.

COMLINK_TLS_CERT_PATH

unset

Pinned Bridge certificate for verify mode.

COMLINK_READ_ONLY

false

When true, only the five read tools are registered (proton_health_check, proton_list_folders, proton_list_messages, proton_search_messages, proton_get_message). Every write/organize/compose tool — including proton_send_message — is not registered and invisible to the client. Overrides COMLINK_ALLOW_SEND.

COMLINK_ALLOW_SEND

false

Master send gate. When false, proton_send_message is not registered — the tool is invisible to the client, not just refusing.

COMLINK_SEND_ALLOWLIST

""

Comma-separated recipients. Exact address (alice@chaosbit.dev) or *@domain wildcard (*@chaosbit.dev). Empty + send enabled = any recipient (logged loudly at startup).

COMLINK_SEND_MAX_PER_HOUR

5

Sliding-window send rate limit.

COMLINK_AUDIT_LOG

~/.comlink/audit.jsonl

Append-only JSONL of every send and delete.

COMLINK_TRANSPORT

stdio

stdio (Phase 1) or streamable-http (Phase 2, remote on Gonk behind Cloudflare Access).

COMLINK_HTTP_HOST

127.0.0.1

Bind address for streamable-http. Use 0.0.0.0 in a container. Ignored for stdio.

COMLINK_HTTP_PORT

8000

Bind port for streamable-http. Ignored for stdio.

COMLINK_HTTP_PATH

/mcp

Mount path for the streamable-http endpoint. Ignored for stdio.

COMLINK_HTTP_ALLOWED_HOSTS

""

Comma-separated Host allowlist for DNS-rebinding protection. When set, protection is on and only these hosts (and https://<host> origins) are accepted — set it to your public hostname (e.g. comlink.chaosbit.dev). When empty, protection is disabled with a logged warning: acceptable behind Cloudflare Access, never for bare-internet exposure.

COMLINK_REQUIRE_ACCESS_JWT

false

Defense-in-depth gate for streamable-http. When true, every HTTP request must carry a valid Cf-Access-Jwt-Assertion header (RS256-verified against the team JWKS, plus aud/iss/exp/iat and the optional email allowlist) or it is rejected with 401 before reaching the MCP app — so a direct in-cluster hit on the ClusterIP can't bypass Cloudflare Access. Requires COMLINK_ACCESS_AUD and COMLINK_ACCESS_TEAM_DOMAIN (startup fails fast otherwise). Ignored for stdio.

COMLINK_ACCESS_AUD

""

Cloudflare Access application AUD tag (an identifier, not a secret). Required when the gate is on.

COMLINK_ACCESS_TEAM_DOMAIN

""

Cloudflare Access team domain, e.g. chaosbit.cloudflareaccess.com. The issuer (https://<team>) and JWKS URL (https://<team>/cdn-cgi/access/certs) are derived from it. Required when the gate is on.

COMLINK_ACCESS_ALLOWED_EMAILS

""

Comma-separated allowlist of email claim values (e.g. brandon@chaosbit.dev,alt@example.com). Empty disables the per-email check (signature/aud/iss/time are still enforced).

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 comlink

6. 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 comlink

If 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:

  1. Env flag (registration). COMLINK_ALLOW_SEND must be true. When it is false, proton_send_message is 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.

  2. 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.

  3. Confirm + rate limit. The call must assert confirm: true (schema-required), and sends are capped at COMLINK_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.jsonl by default) with enough detail to reconstruct what an agent did.


9. Troubleshooting

Symptom

Likely cause

Fix

BridgeUnavailable — "Bridge not reachable on 127.0.0.1:1143"

Bridge app not running

Start Proton Mail Bridge and retry.

AuthFailed — "IMAP login rejected"

Bridge app password rotated

Re-run §3 Keychain store with the new app password from Bridge → Mailbox details.

FolderNotFound

Misspelled folder name

Use proton_list_folders; the error includes fuzzy suggestions.

InvalidTarget — "is a label, not a folder"

Tried to move into a label

Labels coexist with folders in Proton; move into a folder, or apply labels from a Proton client.

SendBlocked

Send gate / allowlist / rate limit

The message names which layer; adjust COMLINK_ALLOW_SEND, COMLINK_SEND_ALLOWLIST, or wait out the rate limit.

UidStale — "UIDVALIDITY changed"

Cached UIDs went stale

Re-run proton_list_messages / proton_search_messages and retry with fresh UIDs.

proton_send_message not in tool list

COMLINK_ALLOW_SEND is not true

Intentional — set it to true (and an allowlist) to register the tool.

Error classes match the design doc §8 taxonomy; every message tells the agent what to do next.


10. References

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read, organize, and send Proton Mail through the local Proton Bridge, with careful gating for sending and attachment access.
      25
      2
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with a Proton Mail mailbox through Proton Bridge, supporting listing, searching, reading, sending, and organizing emails.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to read, search, send, reply, and organize ProtonMail emails through a local ProtonMail Bridge, with automatic Bridge discovery and pinned TLS verification.
      23
      LGPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      10
      180 PyPI
      MIT