proton-workflow-connector

Proton Workflow Connector

Proton Workflow Connector（PWC）は、Proton Mail Bridge を通じて Proton Mail の読み取り、送信、整理、自動化を行うセルフホスト可能な MCP コネクターです。 stdio サーバーを起動するか、Streamable HTTP MCP エンドポイントを呼び出せる、あらゆる MCP クライアントやローカルのエージェントランタイムで動作します。 SimpleLogin のサポートはオプションです。

これは非公式プロジェクトです。Proton AG とは提携関係になく、同社の承認や支援も受けていません。 このコネクターは Bridge が生成した IMAP/SMTP 認証情報を使用します。Proton アカウントのパスワードは受け付けず、Proton のログインセッションも保存しません。

クイックスタート · ワークフローの例 · 機能 · 自動化 · セキュリティ · ドキュメント · コーヒーをおごる

なぜ使うのか？

エージェントが通常、個別に組み合わせる必要のあるメール関連の作業を、1 つのローカルサーバーで実行できます。

• 53 個の Proton Mail ツールを使って、検索、読み取り、送信、返信、転送、下書き作成、ラベル付け、アーカイブ、添付ファイルのダウンロードができます。
• 破壊的なツールの実行には確認を必須にし、dry_run で送信や破壊的な操作を事前確認できます。また、デフォルトで送信 HTML をサニタイズし、一括操作に上限を設け、設定済みの送信者アドレスのみを許可します。
• MCP のポーリング、または Webhook の呼び出し、JSONL の追記、コマンドの実行が可能なバックグラウンドウォッチャーを使って、新着メールや SimpleLogin エイリアスに反応できます。
• エイリアス、連絡先、メールボックスを管理する場合は、SimpleLogin ツールを 13 個追加できます。
• stdio、localhost の Streamable HTTP、OAuth で保護されたホスト型 HTTP 経由で接続できます。

サーバーは合計 68 個のツールを公開します。ツールの完全なリファレンスを参照してください。

仕組み

PWC は MCP サーバーです。クライアントは stdio 経由で起動するか、Streamable HTTP 経由で接続します。

このコネクターは、ローカルの IMAP/SMTP 経由で Proton Mail Bridge と通信します。Bridge はコネクターと同じマシンにインストールされ、サインイン済みで、実行中である必要があります。1 つのコネクタープロセスが 1 つの Bridge アカウントを処理します。

SimpleLogin はオプションです。SIMPLELOGIN_API_KEY が設定されている場合、PWC はエイリアス、連絡先、メールボックス、新しいエイリアスのポーリング用ツールを追加します。設定されていない場合でも、Proton Mail ツールは引き続き動作します。

自動化するには、proton-workflow-watch を実行するか、MCP クライアントからポーリング用ツールを呼び出します。ウォッチャーの出力先には、Webhook、JSONL ファイル、コマンドを指定できます。

クイックスタート

前提条件

• Python 3.11 以降
• Proton Mail Bridge。サインイン済みで実行中であること
• Bridge に表示される IMAP/SMTP ホスト、ポート、ユーザー名、生成されたパスワード
• オプションの SimpleLogin ツールを使う場合のみ、SimpleLogin API キー

1. インストール

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 .

Windows PowerShell では、.venv\Scripts\Activate.ps1 で環境を有効化します。

2. Bridge の認証情報を設定

環境ファイルはリポジトリの外に置いてください。

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

コピーしたファイルを編集し、Proton Mail Bridge に表示される接続情報を設定します。PROTON_BRIDGE_EMAIL にはデフォルトの送信者を設定し、許可する送信者アドレスをすべて PROTON_BRIDGE_SENDER_ADDRESSES に列挙してください。

3. コネクターを実行

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

4. MCP クライアントを接続する

stdio または Streamable HTTP に対応していれば、どの MCP クライアントやローカルエージェントランタイムでも PWC を利用できます。

• stdio：proton-workflow-connector --transport stdio --env-file ... を実行します
• HTTP：コネクターを --transport streamable-http で実行し、クライアントから /mcp に接続します

Claude Code の stdio の例：

claude mcp add --transport stdio --scope user proton-workflow \
  -- "$PWD/.venv/bin/proton-workflow-connector" --transport stdio \
  --env-file ~/.config/proton-workflow-connector/env

Codex の stdio の例：

[mcp_servers.proton_workflow]
command = "/absolute/path/to/repo/.venv/bin/proton-workflow-connector"
args = [
  "--transport", "stdio",
  "--env-file", "/absolute/path/to/private/proton-workflow-connector-env"
]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 120

接続後に server_status を実行します。IMAP、SMTP、SimpleLogin、OAuth の設定、およびサーバーのバージョンを確認しますが、シークレットは返しません。 次に list_folders を実行します。Bridge のフォルダー名は、アカウントやバージョンによって異なります。

一般的なクライアント設定、localhost HTTP、ホスト型 Streamable HTTP、Codex、Claude Code、プラグインラッパーについては、MCP クライアントのセットアップを参照してください。

ワークフローの例

接続後、MCP クライアントに次のように依頼できます。

• 「メールフォルダーを一覧表示し、それぞれの未読件数を表示してください。」
• 「既読にせず、過去 30 日間の未読の請求書を探してください。」
• 「このスレッドの最新メッセージへの返信を下書きしてください。ただし、送信はしないでください。」
• 「このメッセージの PDF 添付ファイルをダウンロードしてください。」
• 「正確な一覧を表示してから、これらのメッセージ UID をアーカイブしてください。」
• 「ショッピング用の SimpleLogin エイリアスを作成し、この販売業者の連絡先を追加してください。」
• 「invoices カーソルを使って、[email protected] からの新着メールを確認してください。」

コネクターは構造化データを MCP クライアントに返します。データの表示方法や、操作の承認を求めるタイミングはクライアントが決定します。

機能

領域	含まれる操作
検索と閲覧	1 つのフォルダーまたは選択可能なすべてのフォルダーを検索し、メッセージやスレッドを読み取り、ヘッダーを確認し、添付ファイルをダウンロードする
送信と下書き	メールの送信、返信、全員への返信、転送、下書きの作成と更新、許可された別の差出人の使用、ファイルの添付
整理	フォルダーの作成と管理、Proton ラベルの適用、フラグの変更、アーカイブ、移動、コピー、復元、迷惑メールやゴミ箱の管理
範囲を限定した一括操作	明示的に指定した UID のリストをプレビューし、既読にする、スターを付ける、移動、コピー、アーカイブ、ゴミ箱に移動、復元、または完全に削除する
自動化	永続カーソルを使ったポーリング、または新着メッセージや新規エイリアスのイベントを Webhook、JSONL ファイル、またはコマンドに送信する
SimpleLogin	オプションの API キーを使って、アカウントデータを確認し、エイリアス、連絡先、メールボックスを管理する
デプロイ	ローカル stdio、localhost Streamable HTTP、または OAuth/OIDC で保護されたホスト型 HTTP

Proton Mail Bridge では連絡先が公開されないため、Proton Contacts は含まれません。

自動化

バックグラウンドウォッチャーは新着メールまたは新規作成された SimpleLogin エイリアスをポーリングし、新しいアイテムごとにイベントを 1 件出力します。

proton-workflow-watch \
  --env-file ~/.config/proton-workflow-connector/env \
  --folder INBOX \
  --webhook-url https://example.com/hooks/proton \
  --interval 60

主な動作：

• 初回実行ではベースラインを確立し、既存のメールボックス内の項目は再送信しません。
• 永続カーソルは再起動後も保持され、IMAP の UIDVALIDITY の変更にも対応します。
• Webhook の配信は少なくとも 1 回行われ、リトライ、指数バックオフ、デッドレター処理に対応します。
• オプションの HMAC-SHA256 署名を使って、Webhook の受信側が各イベントを検証できます。
• イベントに含まれるのはメッセージのメタデータのみです。本文と添付ファイルは、必要に応じて MCP ツールから取得できます。
• JSON ルールを使うと、1 つのウォッチャーから複数の独立したフィルター付きトリガーを実行できます。
• --dry-run を指定すると、配信、操作、カーソルの更新を行わずに、発生するイベントと実行されるルールアクションを確認できます。

イベントスキーマ、フィルター、配信保証、署名検証、ルール、systemd の例については、トリガーと Webhookを参照してください。

セキュリティモデル

このコネクターはプライベートなメールを処理します。デフォルト設定と境界を意図的に明確にしています。

• ローカルの stdio を優先してください。 可能な限り、Bridge とコネクターは同じ信頼できるマシン上で動作させてください。
• 認証情報を非公開にしてください。 Bridge が生成した認証情報と任意の API キーは、Git の管理対象外に置き、ユーザーのみがアクセスできる権限を設定してください。
• 破壊的な操作は確認してください。 完全削除、フォルダーを空にする操作、フォルダーの削除、エイリアスの削除には、明示的なユーザーの意図を確認したうえで confirm=true が必要です。
• 変更前にプレビューしてください。 送信、転送、返信、一括操作、完全削除、フォルダーを空にする操作では、dry_run=true によるプレビューが利用できます。
• メールは信頼できないものとして扱ってください。 読み取り／検索結果ではメールの内容が content_trust: "untrusted" として示され、trusted_html=true を指定しない限り、送信する HTML はサニタイズされます。
• 一括操作の範囲を制限してください。 一括操作ツールでは明示的な数値の UID が必要で、1 回の呼び出しで扱えるメッセージ数は最大 50 件です。
• 送信者を制限してください。 メールの送信元には PROTON_BRIDGE_EMAIL、または PROTON_BRIDGE_SENDER_ADDRESSES に含まれるアドレスのみを指定できます。
• リモートアクセスを保護してください。 ローカル以外の HTTP デプロイでは、Host／Origin ポリシーを意図的に設定する必要があります。インターネット上にデプロイする場合は、HTTPS と外部 OAuth/OIDC プロバイダーが必要です。
• 公開するデータを制限してください。 任意の監査記録には、アドレス、メッセージ本文、添付ファイル、認証情報、トークンは含まれません。
• イベントは信頼できない入力として扱ってください。 メールの件名やエイリアス名は攻撃者が制御できる可能性があります。Webhook の受信側とコマンドでは、イベントフィールドを検証してください。

実際のメールを使用する前に SECURITY.md を、コネクターを localhost の外部に公開する前に ホスト型 HTTP のセットアップ をお読みください。

既知の制約

• コネクターまたはウォッチャーが動作している間は、Proton Mail Bridge を起動したままにする必要があります。
• 1 つのサーバープロセスが接続できる Bridge アカウントは 1 つです。
• Proton Contacts、標準の予約送信、フィルター、アカウント設定、鍵管理は Bridge で公開されていないため、これらをエミュレートすることもありません。
• Proton と SimpleLogin は互換性のあるプッシュ API を提供していないため、新着メールと新規エイリアスのトリガーにはポーリングを使用します。
• トリガーイベントにはメタデータが含まれますが、メッセージ本文や添付ファイルは含まれません。
• All Mail は Bridge の仮想読み取り専用メールボックスです。移動操作と完全削除操作は、書き込み可能なフォルダーから開始してください。

ドキュメント

ガイド	用途
セットアップ	Bridge の設定、プライベートな環境ファイル、フォルダー名、ネットワークモード
ツールリファレンス	68 個すべての MCP ツール、引数、安全上の制限、境界
クライアントのセットアップ	汎用 MCP クライアント、ローカルエージェント、Codex、Claude Code、プラグイン、Streamable HTTP
トリガーと Webhook	ウォッチャーのルール、ペイロード、配信動作、署名検証
ホスト型 HTTP	OAuth/OIDC、HTTPS、Host/Origin の検証、スコープ、監査ログ、systemd
統合テスト	Bridge と SimpleLogin のライブ検証

公式の上流リファレンス：

• Proton Mail Bridge
• Proton IMAP/SMTP のセットアップ
• SimpleLogin API

開発

開発用の依存関係をインストールし、ローカルチェックを実行します。

python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
pytest
python -m compileall -q src
pip-audit
gitleaks detect --redact --config .gitleaks.toml

テストでは合成データを使用するため、実際のメールボックスにアクセスする必要はありません。ライブチェックについては、統合テストで別途説明しています。

貢献とプライバシーに関する要件については、CONTRIBUTING.mdをご覧ください。セキュリティ上の問題は、SECURITY.mdの説明に従って非公開で報告してください。

ライセンス

MIT。LICENSEをご覧ください。