proton-workflow-connector

Proton Workflow Connector

Proton Workflow Connector（PWC）是一个可自托管的 MCP 连接器，可通过 Proton Mail Bridge 读取、发送、整理和自动处理 Proton Mail。 它适用于任何能够启动 stdio 服务或调用 Streamable HTTP MCP 端点的 MCP 客户端或本地 Agent 运行时。 SimpleLogin 支持为可选功能。

这是一个非官方项目，与 Proton AG 无关，未获得其认可或赞助。 该连接器使用由 Bridge 生成的 IMAP/SMTP 凭据，不接受 Proton 账户密码，也不存储 Proton 登录会话。

快速开始 · 工作流示例 · 功能 · 自动化 · 安全 · 文档 · 请我喝杯咖啡

为什么使用它？

使用一个本地服务处理 Agent 通常需要拼凑多个工具才能完成的邮件工作：

• 通过 53 个 Proton Mail 工具搜索、阅读、发送、回复、转发、草拟、添加标签、归档邮件，以及下载附件。
• 对破坏性工具要求确认；通过 dry_run 预览发送和破坏性操作；默认清理发出的 HTML；限制批量操作范围；并且只允许配置的发件人地址。
• 通过 MCP 轮询或后台监视器响应新邮件或 SimpleLogin 别名；监视器可以调用 webhook、追加写入 JSONL，或运行命令。
• 如果需要管理别名、联系人和邮箱，可添加 13 个 SimpleLogin 工具。
• 通过 stdio、本地主机上的 Streamable HTTP，或受 OAuth 保护的托管 HTTP 进行连接。

该服务总共提供 68 个工具。请参阅完整工具参考。

工作原理

PWC 是一个 MCP 服务。客户端通过 stdio 启动它，或通过 Streamable HTTP 连接到它。

该连接器通过本地 IMAP/SMTP 与 Proton Mail Bridge 通信。Bridge 必须安装、登录并在与连接器相同的机器上运行。每个连接器进程服务于一个 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 客户端或本地 Agent 运行时都可以使用 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 文件夹名称因账户和版本而异。

参阅 MCP 客户端设置，了解通用客户端配置、本地主机 HTTP、托管的 Streamable HTTP、Codex、Claude Code 和插件包装器。

示例工作流

连接后，请 MCP 客户端执行以下操作：

• “列出我的邮件文件夹，并显示每个文件夹的未读数量。”
• “查找过去 30 天内未读的发票，不要将其标记为已读。”
• “为此对话中的最新消息起草回复，但不要发送。”
• “下载此消息中的 PDF 附件。”
• “显示确切列表后，将这些消息 UID 归档。”
• “为购物创建一个 SimpleLogin 别名，并为这家商家添加联系人。”
• “使用 invoices 游标轮询来自 [email protected] 的新邮件。”

连接器会向 MCP 客户端返回结构化数据。客户端决定如何呈现这些数据，以及何时请求批准操作。

功能

领域	包含的操作
搜索和阅读	搜索一个文件夹或所有可选文件夹、阅读邮件和对话、查看邮件头，以及下载附件
发送和草稿	发送、回复、回复全部、转发、创建和更新草稿、使用允许的备用发件人，以及附加文件
整理	创建和管理文件夹、应用 Proton 标签、更改标志、归档、移动、复制、恢复，以及管理 Spam 或 Trash
有限批量操作	预览、标记、加星标、移动、复制、归档、移至垃圾箱、恢复，或永久删除明确指定的 UID 列表
自动化	轮询持久游标，或将新消息和新别名事件推送到 webhook、JSONL 文件或命令
SimpleLogin	查看账户数据，并使用可选 API 密钥管理别名、联系人和邮箱
部署	本地 stdio、本地主机 Streamable HTTP，或受 OAuth/OIDC 保护的托管 HTTP

由于 Proton Mail Bridge 不提供 Proton 联系人，因此不包含此功能。

自动化

后台监视器会轮询新邮件或新建的 SimpleLogin 别名，并为每个新项目生成一个事件：

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

主要行为：

• 首次运行会建立基线，不会重放现有邮箱中的内容。
• 持久游标会在重启后保留，并处理 IMAP UIDVALIDITY 变更。
• Webhook 投递采用至少一次语义，并支持重试、指数退避和死信处理。
• 可选的 HMAC-SHA256 签名可让 webhook 接收方验证每个事件。
• 事件仅包含邮件元数据；邮件正文和附件仍可按需通过 MCP 工具获取。
• JSON 规则可从一个监视器运行多个经过独立筛选的触发器。
• --dry-run 会显示将触发哪些事件和规则操作，但不会进行投递、执行操作或推进游标。

阅读触发器和 webhook，了解事件架构、筛选条件、投递保证、签名验证、规则和 systemd 示例。

安全模型

此连接器会处理私人邮件。其默认设置和边界均经过有意明确的设计：

• 优先使用本地 stdio。 尽可能让 Bridge 和连接器运行在同一台可信机器上。
• 妥善保管凭据。 将 Bridge 生成的凭据和可选 API 密钥存放在 Git 之外，并仅授予用户本人权限。
• 确认破坏性操作。 永久删除、清空文件夹、删除文件夹和删除别名，都必须在用户明确表达意图后设置 confirm=true。
• 先预览再修改。 发送、转发、回复、批量操作、永久删除和清空文件夹操作均支持使用 dry_run=true 预览。
• 将邮件视为不可信内容。 读取和搜索结果会将邮件内容标记为 content_trust: "untrusted"；除非设置 trusted_html=true，否则会对外发 HTML 进行净化。
• 限制批量操作。 批量工具要求提供明确的数字 UID，且每次调用默认最多处理 50 封邮件。
• 限制发件人。 只能通过 PROTON_BRIDGE_EMAIL 或 PROTON_BRIDGE_SENDER_ADDRESSES 中的地址发送邮件。
• 保护远程访问。 非本地 HTTP 部署需要明确设置 Host/Origin 策略；互联网部署则必须使用 HTTPS 和外部 OAuth/OIDC 提供商。
• 限制暴露的数据。 可选审计记录不包含地址、邮件正文、附件、凭据和令牌。
• 将事件视为不可信输入。 邮件主题和别名名称可能由攻击者控制；Webhook 接收端和命令必须验证事件字段。

使用真实邮件前，请阅读 SECURITY.md；在将连接器暴露到 localhost 之外之前，请阅读 托管 HTTP 设置。

已知限制

• 连接器或监视器运行期间，Proton Mail Bridge 必须保持运行。
• 一个服务进程只能连接一个 Bridge 账户。
• Bridge 未公开 Proton Contacts、本机定时发送、筛选器、账户设置和密钥管理功能，因此本连接器也不会模拟这些功能。
• 由于 Proton 和 SimpleLogin 不提供兼容的推送 API，新邮件和新别名触发器采用轮询方式。
• 触发器事件包含元数据，不包含邮件正文或附件。
• All Mail 是 Bridge 的虚拟只读邮箱；请从可写文件夹发起移动和永久删除操作。

文档

指南	用途
设置	Bridge 配置、私有环境文件、文件夹名称和网络模式
工具参考	全部 68 个 MCP 工具、参数、安全限制和边界
客户端设置	通用 MCP 客户端、本地 Agent、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。