convez.ai
MCP Server
millsymills-com

protonmail-mcp

millsymills-com/protonmail-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for Proton Mail — manage addresses, custom domains, mail settings, and encryption keys from Claude Code or any MCP host.

Instalação

$npx convez-ai millsymills-com/protonmail-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
75%
Último commit
há 1 semana
Versão
—
Issues abertas
22
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

protonmail-mcp

A Model Context Protocol (MCP) server for Proton Mail, letting Claude Code (or any MCP client) manage addresses, custom domains, mail settings, and encryption keys.

Status

Stage: S2 — read and write tools, writes env-gated default-off, CI green, lockfile committed. Full Proton-parity surface (the climb to S3) is tracked in the feature-parity roadmap.

v2. 32 tools total: 16 reads (always registered) + 15 writes (PROTONMAIL_MCP_ENABLE_WRITES=1) + 1 dangerous write (PROTONMAIL_MCP_ENABLE_WRITES=1 + PROTONMAIL_MCP_ENABLE_DANGEROUS=1).

CapabilityAvailableNotes
Addresses (list, get, set status, delete)yesvia go-proton-api
Create address (alias on custom domain)yesvia internal/protonraw
Update address display name + signatureyesglobal account fields; upstream has no per-address setter
Custom domains (list, get, add, verify, remove)yesvia internal/protonraw
Mail settings (get, update display name + signature)yes
Account settings (get, update telemetry + crash reports)yeslocale update is not exposed by upstream
Encryption keys (list with fingerprint + armored public key)yesvia gopenpgp/v2
Encryption key generation / set primarydeferred to v1.5requires keyring unlock + signed KeyList
Mail search + header inspectionyesmetadata + raw headers; proton_get_message with include_body=true decrypts the plaintext body when the keyring unlocks
Mail draft create/updateyesproton_create_draft, proton_update_draft
Mail label / mark / permanent-deleteyesproton_label_messages, proton_mark_messages, proton_delete_messages (dangerous-gated)
Mail sendv2.xrequires SRP-signed send path
Calendar (list calendars, list events with recurrence expansion, get event)yesread-only; upstream exposes no event-write methods
Drivev3

Install

Requires Go 1.26+ (the toolchain is auto-bumped by go-proton-api master).

The Go module path is github.com/millsymills-com/protonmail-mcp. Build from a clone:

git clone https://github.com/millsymills-com/protonmail-mcp.git
cd protonmail-mcp
go build -o ./protonmail-mcp ./cmd/protonmail-mcp

Or go install github.com/millsymills-com/protonmail-mcp/cmd/protonmail-mcp@latest. Note that go install @latest ignores the replace directive in go.mod (the resty fork), so the clone + go build path above is the supported install; @latest may fail to build until a clean tag exists.

go.mod already pins go-proton-api to a master HEAD pseudo-version and adds a replace directive routing github.com/go-resty/resty/v2 to ProtonMail's fork. Both are required. Do not remove them.

First-time login

./protonmail-mcp login

Prompts for your Proton email, password, and (if 2FA is enabled) an otpauth:// URI or a one-shot 6-digit code. Pasting the URI lets the server refresh sessions silently; pasting a code requires re-login on token expiry.

Credentials are stored in the OS keychain (macOS Keychain / Linux Secret Service) under service protonmail-mcp (default) or in $PROTONMAIL_MCP_STATE_DIR when PROTONMAIL_MCP_CREDENTIAL_BACKEND=file.

./protonmail-mcp status

Confirms the session and prints email + storage. Run ./protonmail-mcp logout to clear stored credentials.

Run as MCP server

Configure your MCP host (Claude Code, etc.) to launch:

./protonmail-mcp

over stdio. By default the server registers read-only tools. To expose mutating tools (create address, add domain, create draft, label messages, update settings):

PROTONMAIL_MCP_ENABLE_WRITES=1 ./protonmail-mcp

Permanent message deletion additionally requires PROTONMAIL_MCP_ENABLE_DANGEROUS=1 — see the tool reference.

Environment variables

VariableValuesDefaultScope
PROTONMAIL_MCP_TRANSPORTstdio | ssestdioalways
PROTONMAIL_MCP_HOSTlisten address127.0.0.1sse only
PROTONMAIL_MCP_PORTlisten portrequired when ssesse only
PROTONMAIL_MCP_SSE_TOKENbearer token clients must send (≥16 chars)required when ssesse only
PROTONMAIL_MCP_CREDENTIAL_BACKENDkeychain | filekeychainalways
PROTONMAIL_MCP_STATE_DIRcredentials dir$STATE_DIRECTORY → $XDG_STATE_HOME/protonmail-mcp → ~/.local/state/protonmail-mcpfile only
PROTONMAIL_MCP_ENABLE_WRITES1/true/yes registers mutating toolsunset (reads only)always
PROTONMAIL_MCP_ENABLE_DANGEROUS1/true/yes additionally registers permanent-delete tools (currently proton_delete_messages); requires PROTONMAIL_MCP_ENABLE_WRITES toounsetalways
PROTONMAIL_MCP_LOG_LEVELdebug for verbose JSON logs to stderrinfoalways
PROTONMAIL_MCP_API_URLoverride Proton API base URL (used in tests)https://mail.proton.me/apialways

For headless Linux deployments (systemd + SSE + file backend), see docs/headless-deployment.md.

Tool reference

Each tool advertises its full input schema and field-by-field description over MCP (tools/list); the handlers live in internal/tools/. Key behaviors worth knowing:

  • proton_update_address updates the global account display name / signature (upstream's SetDisplayName / SetSignature are not per-address). The id parameter is accepted for forward compatibility but ignored. The tool description spells this out.
  • proton_update_core_settings toggles telemetry and crash reports - SetUserSettingsLocale is not exposed by upstream go-proton-api master, so locale update is intentionally absent.
  • proton_list_address_keys uses gopenpgp/v2 to extract the fingerprint + armored public key from each stored key. Private key material never leaves the process.
  • DNS records for custom domains are returned as structured JSON; orchestrate with your DNS provider's MCP (e.g. Gandi MCP) to publish them.

Reads (always)

proton_whoami, proton_session_status, proton_list_addresses, proton_get_address, proton_list_custom_domains, proton_get_custom_domain, proton_get_catchall, proton_get_mail_settings, proton_get_core_settings, proton_list_address_keys, proton_search_messages, proton_get_message, proton_list_labels, proton_list_calendars, proton_list_events, proton_get_event.

Writes (gated: PROTONMAIL_MCP_ENABLE_WRITES=1)

proton_create_address, proton_update_address, proton_set_address_status, proton_delete_address, proton_add_custom_domain, proton_verify_custom_domain, proton_remove_custom_domain, proton_set_catchall, proton_disable_catchall, proton_update_mail_settings, proton_update_core_settings, proton_create_draft, proton_update_draft, proton_label_messages, proton_mark_messages.

Dangerous writes (gated: PROTONMAIL_MCP_ENABLE_WRITES=1 + PROTONMAIL_MCP_ENABLE_DANGEROUS=1)

proton_delete_messages — permanent expunge; irreversible. To move to Trash recoverably, use proton_label_messages with label_id "3" instead.

Security model

  • Credentials and refresh tokens stored in the OS keychain (macOS Keychain / Linux Secret Service, default) or a 0600 state file (file backend for headless Linux deployments).
  • Logs redact any field name containing password, passphrase, token, secret, totp, key.
  • Writes opt-in via env flag - Claude Code's per-tool permission UI provides defense-in-depth.
  • Defaults to stdio - no network listener. An optional SSE transport (PROTONMAIL_MCP_TRANSPORT=sse) binds an HTTP listener on PROTONMAIL_MCP_HOST/PROTONMAIL_MCP_PORT (127.0.0.1 by default). The endpoint requires a bearer token (PROTONMAIL_MCP_SSE_TOKEN, ≥16 chars); clients send Authorization: Bearer <token>. Authentication is enforced regardless of bind address, so even a loopback listener is not reachable by other local users without the token. The SDK's DNS-rebinding (Host-header) protection only applies on a loopback bind - a non-loopback bind logs a warning and relies on the bearer token alone. The connection is plain HTTP - terminate TLS at a reverse proxy if you bind a non-loopback address.
  • Sends x-pm-appversion: macos-bridge@3.24.1 because Proton's API rejects unknown product names with code 2064. We impersonate proton-bridge (live-tested 2026-04-26 against mail.proton.me) - if Proton tightens the minimum (codes 5002/5003), bump the version in internal/session/appversion.go to whatever proton-bridge has tagged latest.

Development

go vet ./...
go test ./... -race                            # unit + harness tests (uses go-proton-api dev server in-process)
go test -tags=integration ./... -race          # extra integration suite for read tools

Manual pre-release checks: docs/testing-checklist.md.

License

MIT.

Ver o original no GitHub

Bom para

Relacionados