Proton Safe MCP

Proton Safe MCP

网站与下载 · 法语版

这是一个与客户端无关的 FastMCP 服务，可通过官方 Proton Mail Bridge 使用 Proton Mail。它可以读取和搜索邮件，并创建带附件的草稿。它有意不具备发送邮件的能力——你可以在 Proton Mail 中检查每一封草稿，并亲自按下“发送”。

该服务通过 STDIO 在本地运行，可供任何兼容 MCP 的客户端使用（Claude Desktop、Claude Code，或任何支持 MCP 的程序）。收到的 PDF、TXT 和 CSV 附件可通过有界文本提取进行检查，而无需暴露其原始字节。发送附件时，会以有界的 base64 数据块上传，因此该服务永远不会接收或读取客户端文件系统路径。

请阅读完整文档，了解设置、配置、工具输入、安全边界和故障排查。

为什么“安全”？

邮件是由攻击者控制的输入。任何发件人都可以在邮件正文中加入对抗性指令，而能读取邮件并持有写入能力工具的 AI Agent，只需一次提示词注入，就可能做出你未曾要求的操作。本项目通过设计限制了潜在损害：

• 不能发送。 代码库中没有 SMTP 客户端，也没有 send_message 工具——有测试对此进行断言。
• **不能删除、不能移动，**也没有下载收到的原始附件的工具。
• 人在回路中。 创建草稿需要在对话中明确确认确切内容，且 Proton Mail 仍要求人工检查并发送。
• 客户端无法访问文件系统。 附件字节以数据块流式传输，并进行声明大小和 SHA-256 校验；路径会被拒绝。
• 仅限环回连接。 使用 STDIO 传输，不开放监听套接字，且 Bridge 主机被硬编码为 127.0.0.1。

这些控制措施可以降低风险，但不会让邮件变得可信。切勿在同一个无人值守的 Agent 工作流中暴露无关的写入能力工具。

架构

安全属性

• 仅使用 STDIO：服务不会打开监听网络套接字。
• Proton Bridge 主机已硬编码为 127.0.0.1（有意不支持 PROTON_BRIDGE_HOST）。
• 不提供 SMTP 客户端、发送工具、删除工具、移动工具或原始已收附件下载工具。
• 邮件和附件读取使用 BODY.PEEK；附件检查仅返回有长度限制的提取文本、 元数据和 SHA-256 摘要，不会返回原始字节或文件。
• 附件输入采用分块 base64，并验证声明的大小和 SHA-256。
• 仅接受 PDF、DOCX、XLSX、PPTX、TXT、CSV、PNG 和 JPEG 上传。
• 附件令牌是随机生成的，短期有效、单次使用，并会在创建草稿前重新验证。
• 创建草稿要求客户端明确声明：用户已在对话中确认确切的收件人、主题、正文和附件。
• Bridge 生成的 IMAP 密码存储在操作系统密钥环中。
• 草稿正文以纯文本形式存储，并附带服务器生成的 HTML 替代版本；该版本会对已确认的正文进行 HTML 转义，因此引用的标记永远不会被渲染。服务器绝不会在正文末尾追加任何内容，包括回复引文。
• Proton Bridge 不会在已保存的草稿中保留回复线程信息。除非用户明确接受可能成为独立草稿的情况，否则会拒绝回复目标。已接受的回复仅提交标头。绝不会从被回复的邮件推导收件人；在 IMAP 写入时会重新验证其 Message-ID，并验证这两个标识符，确保它们都无法继续出现在各自的标头中。
• 收件人、主题和文件夹输入均会针对标头注入和条件注入进行验证。
• 状态文件仅对单个账户可见。Linux 上使用 0700 目录、0600 文件和 O_NOFOLLOW。Windows 上使用受保护的 DACL，仅授予所有者用户和系统账户权限，并通过拒绝重解析点来替代 O_NOFOLLOW。

要求

• 安装了官方 Proton Mail Bridge、已登录且正在运行的 Linux（开发和测试环境为 Ubuntu）。
• 支持 Bridge 的 Proton 套餐。
• 命令行安装需要 Python 3.11–3.14（已在 CI 中测试）；桌面安装程序已捆绑 Python。
• 命令行安装需要 uv。
• 可正常使用的 Secret Service 密钥环（gnome-keyring 或兼容项）。

本仓库已实现 Windows 11 x64 支持，但尚未发布：自动化检查在 Windows Server 上运行，而 Windows 11 端到端验收尚未测试。请参阅 Windows 安装程序说明 和验收清单。

安装

桌面助手 — Ubuntu 24.04，x86_64

下载安装程序， 使用 Ubuntu 的软件包安装程序打开，然后启动 Proton Safe。助手会引导你完成 Bridge 连接，以及在兼容的本地 ChatGPT 桌面版 或 Codex 安装中激活插件。安装程序已包含 Python 和 uv；无需通过终端进行设置。

你仍需要 Proton Mail Bridge、兼容的 Proton 套餐和会话密钥环。 有关前提条件、屏幕截图和修复选项，请参阅桌面指南。 校验和和构建来源信息请见发布页面。

桌面助手 — Windows 11，x64

尚未提供。安装程序、Windows 平台层和构建流水线均已就绪， 但尚未在 Windows 上运行任何验收场景，也没有可供下载的版本。还有两项外部依赖尚未解决：一款完整路径已通过资格验证的 Windows AI 客户端，以及一种可在 CI 中使用的签名身份。

命令行安装 — 其他 MCP 客户端

使用 uv 从 PyPI 安装经过审核的发行版：

uv tool install proton-safe-mcp==2.3.1

如需从源代码进行开发：

git clone https://github.com/fbossiere/proton-safe-mcp.git
cd proton-safe-mcp
uv sync --extra dev

在 MCP 进程环境中设置 Proton 地址和 Bridge IMAP 端口。此处绝不会设置凭据：

export PROTON_BRIDGE_USER="[email protected]"
export PROTON_IMAP_PORT="1143"

如需以同一账户中的其他 Proton 地址起草邮件，请在相同环境中添加可选的发件人允许列表，并以逗号分隔纯地址：

export PROTON_BRIDGE_ALIASES="[email protected],[email protected]"

存储 Bridge 生成的 IMAP 密码（显示在 Bridge 界面中），而不是你的 Proton 账户密码：

proton-safe-mcp setup

Bridge 显示的值因安装而异，且仅适用于本地 Bridge。

在 MCP 客户端中注册

使用以下逻辑字段配置本地 STDIO 服务。如果客户端不会继承你的 shell PATH，请使用 command -v proton-safe-mcp 获取绝对命令路径：

{
  "name": "proton-safe",
  "transport": "stdio",
  "command": "/absolute/path/to/proton-safe-mcp",
  "args": ["serve"],
  "env": {
    "PROTON_BRIDGE_USER": "[email protected]",
    "PROTON_IMAP_PORT": "1143"
  }
}

如果起草邮件时可能使用多个 From 地址，请将 PROTON_BRIDGE_ALIASES 放在同一个 env 块中。参见发件人地址。

请勿将 PROTON_BRIDGE_PASSWORD 放入客户端配置中。服务会从 setup 建立的 OS 密钥环中读取该值。

可查看 Claude Code、Cursor 和 VS Code 的复制粘贴说明。 AI 编码 Agent 可以参阅遵循安全约束的 llms-install.md 指南。

验证完整的本地设置，不打印凭据、地址或邮箱数据：

proton-safe-mcp doctor

OpenAI 插件

此代码库包含一个供 ChatGPT 和 Codex 使用的私有、本地优先 Proton Safe 插件。它基于同一个受限 MCP 服务，提供注重安全的邮件审查和起草工作流：

• ChatGPT 桌面版和 Codex 可直接在 Bridge 所在机器上启动随附的 STDIO 配置，无需隧道或专用服务；
• 不需要打包的工作流技能时，仍可直接注册 MCP；
• ChatGPT 网页版或另一台机器上的客户端可以选择通过 OpenAI Secure MCP Tunnel 连接 Bridge 主机，无需开放入站端口；
• 远程部署仍会将 proton-safe-mcp 与 Proton Mail Bridge 部署在一起，并将 IMAP 固定为 127.0.0.1。

请参阅 OpenAI 插件指南，了解 ChatGPT 桌面版/Codex 的本地安装、直接注册 MCP 以及可选的远程隧道。

已安装插件，但没有 Proton 工具？ 随附的 MCP 配置会从启动 Codex 的环境中转发 PROTON_BRIDGE_USER 和 PROTON_IMAP_PORT，但不会定义它们的值。在 Ubuntu 上，即使 ~/.config/environment.d/*.conf 文件配置正确，也可能仍需重新加载用户管理器；而 GNOME 和已运行的终端可能会保留先前的环境。如果从菜单重新启动后仍没有工具，请先从已加载该文件的终端启动一次 ChatGPT。通过终端启动仅用于诊断，并非每次启动都必须这样做；故障排除指南还提供了持久的按用户菜单启动器。重新安装任何内容之前，请按照注重隐私的 Ubuntu 恢复流程 或参阅 常见问题。

帮助测试引导流程。 Linux 和 Proton Mail Bridge 用户可以参与 10 分钟外部测试，并提交注重隐私的安装反馈。

可用的 MCP 工具

类别	工具	说明
只读邮件	mailbox_status	桥接连接状态 + INBOX 计数
	list_folders
	list_sender_addresses	草稿可使用的固定发件人地址允许列表
	list_messages	不会将邮件标记为已读
	search_messages	防注入的 IMAP TEXT 搜索
	read_message	有长度限制的纯文本；不包含附件字节
	extract_attachment_text	有长度限制的 PDF/TXT/CSV 文本；不包含原始字节或文件
	get_reply_context	候选回复收件人、Re: 主题和有长度限制的引用内容——均为建议
附件暂存	begin_attachment_upload	声明文件名、类型、大小和 SHA-256
	upload_attachment_chunk	按顺序上传 base64 分块
	finish_attachment_upload	校验哈希并返回一次性令牌
	discard_attachment
草稿	create_confirmed_draft	需要明确确认；回复目标还需要接受可能单独生成的草稿

这里有意不提供 send_message 工具。

附件与草稿工作流

MCP 客户端只需能够获取文件字节并调用工具。此流程不依赖特定客户端、服务或本地目录。

1. 计算文件的准确字节长度和 SHA-256。
2. 调用 begin_attachment_upload(filename, content_type, size_bytes, sha256_hex)。
3. 将连续的二进制数据块编码为 base64，且每块不超过返回的 max_chunk_bytes。
4. 按 0, 1, 2… 的索引调用 upload_attachment_chunk(upload_id, chunk_index, data_base64)。
5. 调用 finish_attachment_upload(upload_id)，并保留返回的 attachment_token。
6. 向用户展示准确的收件人、主题、完整正文和附件列表。
7. 在对话中获得明确确认后，调用 create_confirmed_draft(..., user_confirmed=true, attachment_tokens=[token])。
8. 打开 Proton Mail，检查草稿，然后手动发送。

第 8 步是人工把关环节，也是唯一重要的一步：服务端没有 SMTP 实现，因此它创建的草稿在你于 Proton Mail 中按下“发送”之前，无法离开你的帐户。如果没有草稿使用已上传的附件，附件将在 30 分钟后过期。

本地管理

proton-safe-mcp doctor   # check the local setup without printing private data
proton-safe-mcp setup    # store the Bridge-generated IMAP password in the OS keyring
proton-safe-mcp serve    # run the MCP server over STDIO

配置参考

变量	默认值	用途
PROTON_BRIDGE_USER	必填	在 Bridge 中配置的 Proton 地址
PROTON_BRIDGE_ALIASES	空	以逗号分隔的其他发件人地址，草稿可使用这些地址
PROTON_IMAP_PORT	1143	本地 Bridge IMAP 端口
PROTON_MCP_STATE_DIR	~/.local/state/proton-safe-mcp	私有附件暂存状态
PROTON_MCP_MAX_ATTACHMENT_BYTES	20971520	单个文件和单封草稿的最大值，上限为 25 MiB
PROTON_MCP_MAX_RECEIVED_ATTACHMENT_BYTES	10485760	接收文件的提取上限，上限为 25 MiB
PROTON_MCP_MAX_CHUNK_BYTES	393216	解码后分块的最大值，上限为 1 MiB
PROTON_MCP_UPLOAD_TTL_SECONDS	1800	附件暂存时长
PROTON_MCP_MAX_BODY_CHARS	100000	外发草稿正文长度上限

有意不支持 PROTON_BRIDGE_HOST。

对于没有 Secret Service 密钥环的隔离容器，可将 Bridge 生成的 IMAP 密码填入 PROTON_BRIDGE_PASSWORD。请避免在桌面 MCP 客户端配置中使用此回退方式： 环境变量值可能会被客户端进程或其诊断信息读取。

开发

uv sync --extra dev
uv run pytest --cov      # tests with coverage
uv run ruff check .      # lint
uv run ruff format .     # format
uv run mypy              # strict type checking

开发无需 Proton Bridge：测试套件会模拟 IMAP 层。测试涵盖路径拒绝、MIME 限制、接收附件的大小和格式拒绝、有长度限制的 PDF/文本提取、按顺序处理分块、大小/哈希校验、令牌使用、标头注入、草稿确认、收件人和附件限制，以及 HTML 转文本清理。

请参阅 CONTRIBUTING.md，了解审查时会强制执行的设计规则。

威胁模型的局限性

在自主工作流中依赖此服务前，请先阅读：

• 模型必然会看到它读取的任何邮件，以及它创建或上传的任何附件。
• 提取的附件文本由攻击者控制，可能包含提示注入。服务会限制返回文本的长度，但不会使其可信，也不会执行 OCR 或恶意软件扫描。
• 上传的附件字节会临时存储在只有 Unix 账户可读取的文件中。请使用全盘加密。
• 服务无法检查周围的对话。user_confirmed: true 是客户端的声明，因此确认步骤取决于客户端是否遵守规则。它可以减少意外，但无法防范受攻击者影响的客户端。
• 此服务创建的草稿在发送前不会生效，但仍可能被精心写成看起来像是你写的。请在 Proton Mail 中阅读草稿后再发送，尤其要核对收件人。
• Secure MCP Tunnel 可使服务不暴露于公共互联网，但返回给 OpenAI 产品的邮件内容仍会跨越本地 Bridge 边界，并由该产品处理。
• 工具注释和对话式确认说明是给客户端的指引，不是授权控制。服务实际强制执行的是输入验证，以及不具备任何发送、删除或移动能力。
• Proton Bridge 的自签名 TLS 证书不会经过验证。只有因为目标主机固定为 127.0.0.1 且无法更改，这种做法在此处才可接受。

安全

如需报告漏洞，请使用 GitHub 私密漏洞报告——切勿提交公开 Issue。请参阅 SECURITY.md。

许可证

MIT © 2026 Francois Bossiere。

本项目与 Proton AG 无关联，也未获得其认可。“Proton Mail”和“Proton Mail Bridge”是 Proton AG 的商标。