{
  "markdown": "# Proton Workflow Connector\n\n[![CI](https://github.com/NtrpyDev/proton-workflow-connector/actions/workflows/ci.yml/badge.svg)](https://github.com/NtrpyDev/proton-workflow-connector/actions/workflows/ci.yml)\n[![Secret scan](https://github.com/NtrpyDev/proton-workflow-connector/actions/workflows/secret-scan.yml/badge.svg)](https://github.com/NtrpyDev/proton-workflow-connector/actions/workflows/secret-scan.yml)\n[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\nProton Workflow Connector (PWC) is a self-hosted MCP connector for reading, sending, organizing, and automating Proton Mail through Proton Mail Bridge.\nIt works with any MCP client or local agent runtime that can launch a stdio server or call a Streamable HTTP MCP endpoint.\nSimpleLogin support is optional.\n\nThis is an unofficial project. It is not affiliated with, endorsed by, or sponsored by Proton AG.\nThe connector uses Bridge-generated IMAP/SMTP credentials. It does not accept Proton account passwords or store Proton login sessions.\n\n[Quick start](#quick-start) · [Example workflows](#example-workflows) · [Capabilities](#capabilities) · [Automations](#automations) · [Security](#security-model) · [Documentation](#documentation) · [Buy Me a Coffee](https://buymeacoffee.com/ntrpydev)\n\n## Why use it?\n\nUse one local server for the mail work agents usually have to piece together:\n\n- Search, read, send, reply, forward, draft, label, archive, and download attachments through 53 Proton Mail tools.\n- Require confirmation for destructive tools, preview sends and destructive operations with `dry_run`, sanitize outbound HTML by default, bound bulk operations, and allow only configured sender addresses.\n- React to new mail or SimpleLogin aliases through MCP polling or a background watcher that can call a webhook, append JSONL, or run a command.\n- Add 13 SimpleLogin tools when you want alias, contact, and mailbox management.\n- Connect over stdio, localhost Streamable HTTP, or OAuth-protected hosted HTTP.\n\nThe server exposes 68 tools in total. See the [complete tool reference](docs/TOOLS.md).\n\n## How it works\n\nPWC is an MCP server. Your client starts it over stdio or connects to it over Streamable HTTP.\n\nThe connector talks to Proton Mail Bridge over local IMAP/SMTP. Bridge must be installed, signed in, and running on the same machine as the connector. One connector process serves one Bridge account.\n\nSimpleLogin is optional. If `SIMPLELOGIN_API_KEY` is set, PWC adds alias, contact, mailbox, and new-alias polling tools. If it is unset, the Proton Mail tools still work.\n\nFor automation, run `proton-workflow-watch` or call the polling tools from your MCP client. Watcher output can go to a webhook, a JSONL file, or a command.\n\n## Quick start\n\n### Prerequisites\n\n- Python 3.11 or newer\n- [Proton Mail Bridge](https://proton.me/mail/bridge), signed in and running\n- The IMAP/SMTP host, ports, username, and generated password shown by Bridge\n- A SimpleLogin API key only if you want the optional SimpleLogin tools\n\n### 1. Install\n\n```bash\ngit clone https://github.com/NtrpyDev/proton-workflow-connector.git\ncd proton-workflow-connector\npython -m venv .venv\nsource .venv/bin/activate\npython -m pip install .\n```\n\nOn Windows PowerShell, activate the environment with `.venv\\Scripts\\Activate.ps1`.\n\n### 2. Configure Bridge credentials\n\nKeep the environment file outside the repository:\n\n```bash\nmkdir -p ~/.config/proton-workflow-connector\ncp .env.example ~/.config/proton-workflow-connector/env\nchmod 600 ~/.config/proton-workflow-connector/env\n```\n\nEdit the copied file with the connection details shown in Proton Mail Bridge. Set `PROTON_BRIDGE_EMAIL` to the default sender and list every permitted sender address in `PROTON_BRIDGE_SENDER_ADDRESSES`.\n\n### 3. Run the connector\n\n```bash\nproton-workflow-connector --transport stdio \\\n  --env-file ~/.config/proton-workflow-connector/env\n```\n\n### 4. Connect an MCP client\n\nAny MCP client or local agent runtime can use PWC as long as it supports stdio or Streamable HTTP:\n\n- stdio: run `proton-workflow-connector --transport stdio --env-file ...`\n- HTTP: run the connector with `--transport streamable-http` and point the client at `/mcp`\n\nClaude Code stdio example:\n\n```bash\nclaude mcp add --transport stdio --scope user proton-workflow \\\n  -- \"$PWD/.venv/bin/proton-workflow-connector\" --transport stdio \\\n  --env-file ~/.config/proton-workflow-connector/env\n```\n\nCodex stdio example:\n\n```toml\n[mcp_servers.proton_workflow]\ncommand = \"/absolute/path/to/repo/.venv/bin/proton-workflow-connector\"\nargs = [\n  \"--transport\", \"stdio\",\n  \"--env-file\", \"/absolute/path/to/private/proton-workflow-connector-env\"\n]\ndefault_tools_approval_mode = \"prompt\"\nstartup_timeout_sec = 20\ntool_timeout_sec = 120\n```\n\nRun `server_status` after connecting. It checks IMAP, SMTP, SimpleLogin, OAuth configuration, and the server version without returning secrets.\nThen run `list_folders`; Bridge folder names vary by account and version.\n\nSee [MCP client setup](docs/CLIENTS.md) for generic client configuration, localhost HTTP, hosted Streamable HTTP, Codex, Claude Code, and the plugin wrapper.\n\n## Example workflows\n\nOnce connected, ask your MCP client to:\n\n- \"List my mail folders and show the unread count for each.\"\n- \"Find unread invoices from the last 30 days without marking them read.\"\n- \"Draft a reply to the latest message in this thread, but do not send it.\"\n- \"Download the PDF attachments from this message.\"\n- \"Archive these message UIDs after showing me the exact list.\"\n- \"Create a SimpleLogin alias for shopping and add a contact for this merchant.\"\n- \"Poll for new mail from `billing@vendor.example` using the `invoices` cursor.\"\n\nThe connector returns structured data to the MCP client. The client decides how to present it and when to request approval for actions.\n\n## Capabilities\n\n| Area | Included operations |\n| --- | --- |\n| Search and reading | Search one folder or all selectable folders, read messages and threads, inspect headers, and download attachments |\n| Sending and drafts | Send, reply, reply-all, forward, create and update drafts, use allowed alternate senders, and attach files |\n| Organization | Create and manage folders, apply Proton labels, change flags, archive, move, copy, restore, and manage Spam or Trash |\n| Bounded bulk actions | Preview, mark, star, move, copy, archive, trash, restore, or permanently delete explicit UID lists |\n| Automations | Poll persistent cursors or push new-message and new-alias events to a webhook, JSONL file, or command |\n| SimpleLogin | Inspect account data and manage aliases, contacts, and mailboxes with an optional API key |\n| Deployment | Local stdio, localhost Streamable HTTP, or OAuth/OIDC-protected hosted HTTP |\n\nProton Contacts are not included because Proton Mail Bridge does not expose them.\n\n## Automations\n\nThe background watcher polls for new mail or newly created SimpleLogin aliases and emits one event per new item:\n\n```bash\nproton-workflow-watch \\\n  --env-file ~/.config/proton-workflow-connector/env \\\n  --folder INBOX \\\n  --webhook-url https://example.com/hooks/proton \\\n  --interval 60\n```\n\nKey behavior:\n\n- The first run establishes a baseline and does not replay the existing mailbox.\n- Persistent cursors survive restarts and account for IMAP `UIDVALIDITY` changes.\n- Webhook delivery is at-least-once, with retries, exponential backoff, and dead-letter handling.\n- An optional HMAC-SHA256 signature lets webhook receivers verify each event.\n- Events contain message metadata only; bodies and attachments remain available on demand through MCP tools.\n- JSON rules can run several independently filtered triggers from one watcher.\n- `--dry-run` shows which events and rule actions would fire without delivering, acting, or advancing cursors.\n\nRead [Triggers and webhooks](docs/WATCH.md) for event schemas, filters, delivery guarantees, signature verification, rules, and systemd examples.\n\n## Security model\n\nThis connector processes private mail. Its defaults and boundaries are intentionally explicit:\n\n- **Prefer local stdio.** Bridge and the connector should stay on the same trusted machine whenever possible.\n- **Keep credentials private.** Store Bridge-generated credentials and optional API keys outside Git with user-only permissions.\n- **Confirm destructive actions.** Permanent deletion, empty-folder operations, folder deletion, and alias deletion require `confirm=true` after explicit user intent.\n- **Preview before mutating.** Sends, forwards, replies, bulk actions, permanent delete, and empty-folder operations support `dry_run=true` previews.\n- **Treat mail as untrusted.** Read/search results mark email content as `content_trust: \"untrusted\"`, and outbound HTML is sanitized unless `trusted_html=true`.\n- **Bound bulk operations.** Bulk tools require explicit numeric UIDs and default to a maximum of 50 messages per call.\n- **Restrict senders.** Mail can only be sent from `PROTON_BRIDGE_EMAIL` or an address in `PROTON_BRIDGE_SENDER_ADDRESSES`.\n- **Protect remote access.** Non-local HTTP deployments require deliberate Host/Origin policy; internet deployments require HTTPS and an external OAuth/OIDC provider.\n- **Limit exposed data.** Optional audit records exclude addresses, message bodies, attachments, credentials, and tokens.\n- **Treat events as untrusted input.** Email subjects and alias names can be attacker-controlled; webhook receivers and commands must validate event fields.\n\nRead [SECURITY.md](SECURITY.md) before using real mail and [Hosted HTTP setup](docs/HOSTING.md) before exposing the connector beyond localhost.\n\n## Known boundaries\n\n- Proton Mail Bridge must remain running while the connector or watcher is active.\n- One server process connects to one Bridge account.\n- Proton Contacts, native scheduled sending, filters, account settings, and key management are not exposed by Bridge and are not emulated.\n- New-mail and new-alias triggers use polling because Proton and SimpleLogin do not provide a compatible push API.\n- Trigger events include metadata, not message bodies or attachments.\n- `All Mail` is a virtual read-only Bridge mailbox; start move and permanent-delete operations from a writable folder.\n\n## Documentation\n\n| Guide | Use it for |\n| --- | --- |\n| [Setup](docs/SETUP.md) | Bridge configuration, private environment files, folder names, and network modes |\n| [Tool reference](docs/TOOLS.md) | All 68 MCP tools, arguments, safety limits, and boundaries |\n| [Client setup](docs/CLIENTS.md) | Generic MCP clients, local agents, Codex, Claude Code, plugins, and Streamable HTTP |\n| [Triggers and webhooks](docs/WATCH.md) | Watcher rules, payloads, delivery behavior, and signature verification |\n| [Hosted HTTP](docs/HOSTING.md) | OAuth/OIDC, HTTPS, Host/Origin validation, scopes, audit logs, and systemd |\n| [Integration tests](docs/INTEGRATION_TESTS.md) | Live Bridge and SimpleLogin verification |\n\nOfficial upstream references:\n\n- [Proton Mail Bridge](https://proton.me/mail/bridge)\n- [Proton IMAP/SMTP setup](https://proton.me/support/imap-smtp-and-pop3-setup)\n- [SimpleLogin API](https://github.com/simple-login/app/blob/master/docs/api.md)\n\n## Development\n\nInstall the development dependencies and run the local checks:\n\n```bash\npython -m pip install -e \".[dev]\"\nruff check .\nruff format --check .\npytest\npython -m compileall -q src\npip-audit\ngitleaks detect --redact --config .gitleaks.toml\n```\n\nTests use synthetic data and do not require access to a real mailbox. Live checks are documented separately in [Integration tests](docs/INTEGRATION_TESTS.md).\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and privacy requirements. Report security issues privately as described in [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n<!-- mcp-name: io.github.NtrpyDev/proton-workflow-connector -->\n",
  "bytes": 11979,
  "sha": "1a08dcf15935e97df06e2590ffd3f4722a380f6211fd4cd094c42a44cfb5eb73",
  "repo_slug": "ntrpydev/proton-workflow-connector",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ntrpydev_proton_workflow_conne_8dde39bf/readme"
}