Proton Workflow Connector

Proton Workflow Connector (PWC) is a self-hosted MCP connector for reading, sending, organizing, and automating Proton Mail through Proton Mail Bridge. It works with any MCP client or local agent runtime that can launch a stdio server or call a Streamable HTTP MCP endpoint. SimpleLogin support is optional.

This is an unofficial project. It is not affiliated with, endorsed by, or sponsored by Proton AG. The connector uses Bridge-generated IMAP/SMTP credentials. It does not accept Proton account passwords or store Proton login sessions.

Quick start · Example workflows · Capabilities · Automations · Security · Documentation · Buy Me a Coffee

Why use it?

Use one local server for the mail work agents usually have to piece together:

• Search, read, send, reply, forward, draft, label, archive, and download attachments through 53 Proton Mail tools.
• 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.
• 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.
• Add 13 SimpleLogin tools when you want alias, contact, and mailbox management.
• Connect over stdio, localhost Streamable HTTP, or OAuth-protected hosted HTTP.

The server exposes 68 tools in total. See the complete tool reference.

How it works

PWC is an MCP server. Your client starts it over stdio or connects to it over Streamable HTTP.

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

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

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

Quick start

Prerequisites

• Python 3.11 or newer
• Proton Mail Bridge, signed in and running
• The IMAP/SMTP host, ports, username, and generated password shown by Bridge
• A SimpleLogin API key only if you want the optional SimpleLogin tools

1. Install

git clone https://github.com/NtrpyDev/proton-workflow-connector.git
cd proton-workflow-connector
python -m venv .venv
source .venv/bin/activate
python -m pip install .

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1.

2. Configure Bridge credentials

Keep the environment file outside the repository:

mkdir -p ~/.config/proton-workflow-connector
cp .env.example ~/.config/proton-workflow-connector/env
chmod 600 ~/.config/proton-workflow-connector/env

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

3. Run the connector

proton-workflow-connector --transport stdio \
  --env-file ~/.co

... [View full README on GitHub](https://github.com/ntrpydev/proton-workflow-connector#readme)