Proton Mail Bridge MCP 和 CLI

为 Claude Desktop 打造的 Proton Mail，以正确的方式实现。

🌉 Proton Mail Bridge MCP 是一个本地优先的 Proton Mail 集成，适用于 Claude Desktop 和终端。它允许你通过 Proton Bridge 读取、搜索、起草、发送、同步和管理 Proton Mail，同时提供完整的 MCP 服务器和真实的 CLI。

设置完成后，Claude Desktop 会使用你电脑上安装的稳定本地版本。它不受限于单个仓库、工作区或聊天文件夹。

简单理解：

1. 在你的电脑上安装 Proton Mail Bridge MCP

2. 将其连接到 Claude Desktop

你不需要了解 MCP 的内部原理即可使用它。如果 Proton Bridge 已经在你的机器上运行，设置非常简单。

60 秒设置

如果 Proton Bridge 已经在你的机器上运行：

git clone https://github.com/googlarz/proton-mail-bridge-mcp.git
cd proton-mail-bridge-mcp
npm install
npm run setup:claude-desktop

然后：

1. 保持 Proton Bridge 开启

2. 重启 Claude Desktop

3. 打开任意聊天并检查 + -> Connectors -> proton-mail-bridge

如果你还需要快速的终端健康检查：

npm run check:claude-desktop
proton-mail-bridge doctor --json

使用本 README 中显示的 npm run ... 命令。

这一点很重要，因为设置和安装程序入口点位于构建后的 dist/ 输出中，npm 脚本已经为你指向了正确的文件。

为什么人们使用它

• 无需切换工具，即可在 Claude Desktop 中处理 Proton Mail。

• 更快地搜索发票、旅行邮件、文档和邮件线程。

• 通过 Proton Bridge 起草、回复、转发和发送邮件。

• 在 Claude Desktop 或直接在终端中使用相同的后端。

• 快速诊断 Claude Desktop 和 Proton Bridge 的设置问题。

为什么存在这个项目

Claude 目前有原生的 Gmail 连接器，但还没有原生的 Proton Mail 连接器。本项目为 Proton 用户填补了这一空白。

最初的 proton-mail-pro-mcp 想法确实很有前途，但我开始使用的代码库无法直接使用。我将其重构为一个可用的 MCP 服务器，实现了缺失的部分，并添加了一长串改进，使其在日常使用中真正有用。

它的优势：

• 通过 Proton Bridge 提供真正的 Proton 支持。

• 读写操作：起草、发送、回复、转发、归档、移至垃圾箱、恢复。

• 附件内容访问和文件保存。

• 本地索引、线程分类、跟进视图和后台刷新。

• 本地优先的 Claude Desktop 设置，安装后即可在全机使用。

• 一个真正的 CLI，用于同步、搜索、读取、诊断、Claude Desktop 维护以及从终端执行完整的 MCP 工具调用。

预期效果：

• 它与 Proton Bridge 一起在你的机器上本地运行。

• 它插入到 Claude Desktop 中，但不是官方的 Claude 连接器。

• 来源链接来自 MCP 层，而不是原生的 Proton Webmail 链接。

• 安装后，Claude Desktop 可以在该电脑的所有聊天中使用它。

信任与安全

• 在你的机器上本地运行。

• 通过你机器上的 Proton Bridge 与 Proton Mail 通信。

• 不需要托管的邮件中继或远程 URL 服务。

• 如果你想要更安全的默认设置，可以以只读模式运行。

• 如果你不希望在配置中包含原始凭据，支持 *_FILE 和 *_COMMAND 密钥。

• 仅当你明确使用这些功能时，才会执行发送或邮箱修改操作。

已验证的功能

这些路径已针对真实的 Proton Bridge 设置进行了实时测试：

• IMAP 连接和文件夹列表

• SMTP 连接和发送

• 完整邮件读取

• 本地索引和增量同步

• 线程视图、摘要和跟进工作流

• 远程草稿同步到 Proton 草稿箱

• 附件列表和保存

• CLI 命令及通用 MCP 工具调用

它能做什么

• 通过 Proton Bridge IMAP 和 SMTP 将 Claude 连接到 Proton Mail。

• 读取文件夹、邮件和附件。

• 搜索实时邮件和本地索引邮件。

• 创建、更新、同步和发送草稿。

• 发送邮件、回复和转发。

• 标记已读或未读、加星或取消加星、移动、归档、移至垃圾箱、恢复和删除。

• 构建带有增量同步检查点的本地 SQLite 索引。

• 使用 IMAP IDLE 感知刷新来监视邮箱更改。

• 从 IMAP 数据重构标准化的标签和线程。

• 对更多附件类型进行分类，包括内联图像、日历邀请、压缩包和签名文件。

• 生成可操作的线程视图、收件箱摘要、跟进候选、会议准备、文档查找视图和线程简报。

• 支持针对批量和线程邮箱操作的更安全的试运行预览。

• 发出 MCP 资源链接和结构化的源元数据，用于下游引用样式的渲染。

需要了解的事项

• 它使用 Proton Bridge。 原因：本项目通过 Proton Bridge 提供的本地 IMAP 和 SMTP 访问进行连接。

• 它在本地运行。 原因：Proton Bridge 通常在你自己的机器上运行，因此该 MCP 服务器也被设计为在本地运行。

• 线程和标签是从 IMAP 数据重构的。 原因：Proton 原生的线程和标签对象无法通过官方的 Claude 连接器路径获取。

• 附件处理很广泛，但不是万能的。 原因：常见情况处理得很好，包括日历邀请和常见的文档/图像附件，但电子邮件 MIME 格式在不同的发件人和客户端之间仍然可能很混乱。

仍然缺失的功能及其原因

• 开箱即用不支持远程 URL 连接器。 原因：当前产品与你机器上的 Proton Bridge 通信，而 Proton Bridge 通常是本地的，不是托管服务。

• 没有官方的 Claude 身份验证流程或原生的 Proton 深层链接。 原因：这些需要 Anthropic 的平台级支持以及 Proton 提供比 IMAP 和 SMTP 更丰富的支持。

• 没有真正的 Proton 原生对话模型。 原因：本项目从 Bridge 邮件数据重构线程和标签，而不是调用更丰富的 Proton 特定 API。

• 未来仍有可能实现更原生的 Proton 体验。 原因：如果 Proton 发布了更好的公共集成路径，或者更清晰的本地/托管 Bridge 方案，本项目可以更接近原生的 Gmail 体验。我正在等待该生态系统的改善。

开始之前

你需要：

1. Claude Desktop

2. Node.js 18 或更高版本

3. 一个 Proton 账户

4. 已安装并登录 Proton Bridge

5. 大约 10 分钟时间

从 Proton Bridge 中，你需要：

• IMAP 主机

• IMAP 端口

• SMTP 主机

• SMTP 端口

• 用户名

• Bridge 密码

对于大多数本地 Bridge 设置，默认值为：

• IMAP 主机: 127.0.0.1

• IMAP 端口: 1143

• SMTP 主机: 127.0.0.1

• SMTP 端口: 1025

🚀 设置概述

设置分为两部分：

1. 安装本地 MCP 服务器

2. 将其连接到 Claude Desktop

正常路径是使用引导式设置向导。手动路径仅适用于想要更多控制权的用户。

重要提示：

• 仓库文件夹仅用于安装或更新 MCP

• 设置完成后，Claude Desktop 本身将使用稳定的全机运行时

• 因此，这适用于你电脑上的通用 Claude Desktop 使用，而不仅仅是一个项目文件夹

第 1 部分：在你的电脑上安装 Proton Mail Bridge MCP

1. 🔐 打开 Proton Bridge

打开 Proton Bridge 并确保你的账户已连接。

在 Bridge 中，打开邮箱详细信息或“配置电子邮件客户端”视图并复制：

• IMAP 主机和 IMAP 端口

• SMTP 主机和 SMTP 端口

• 用户名

• Bridge 密码

保持 Proton Bridge 运行。使用此 MCP 时不要关闭它。

2. 📥 下载项目

git clone https://github.com/googlarz/proton-mail-bridge-mcp.git
cd proton-mail-bridge-mcp
npm install

如果愿意，你也可以从最新的 GitHub 发布版本下载源代码，而不是克隆仓库。

如果你的机器上没有 npm，请先安装 Node.js 18+，然后再次运行命令。

此时，MCP 服务器文件已在你的电脑上，并准备好进行 Claude Desktop 步骤。

你可以将仓库克隆到任何你喜欢的地方。此文件夹用于安装和更新。设置完成后，Claude Desktop 不会一直绑定到此文件夹。

第 2 部分：告诉 Claude Desktop 使用它

3. 🪄 为 Claude Desktop 设置 Proton Mail Bridge MCP

npm run setup:claude-desktop

此命令不会安装 Claude Desktop 应用程序本身。

Claude Desktop 应该已经安装好了。

此命令的作用是：

• 检查标准的 Proton Bridge 本地端口

• 询问你的 Proton Bridge 用户名和 Bridge 密码

• 使用标准的本地 Bridge 地址，除非你覆盖它们

• 构建此 MCP 服务器

• 为 Claude Desktop 在此仓库之外安装一个稳定的本地运行时副本

• 写入 Claude Desktop 配置文件，告诉 Claude 如何启动该已安装的运行时

• 将此 MCP 服务器需要的 PROTONMAIL_* 值存储在该本地 Claude Desktop 配置中

• 在更改之前备份旧的 Claude Desktop 配置

简单来说：

• 此命令为这台电脑上的 Claude Desktop 安装或更新 Proton Mail Bridge MCP 集成

• 它不会安装 Claude Desktop 应用程序本身

• 它不会将 Claude 锁定在你运行它的文件夹中

4. 🔁 重启 Claude Desktop

向导完成后：

• 重启 Claude Desktop

• 保持 Proton Bridge 开启

• 在 Claude Desktop 中打开任意聊天

• 点击聊天框附近的 + 按钮，然后打开 Connectors

• 确认 proton-mail-bridge 出现在那里，并且工具可用

• 如果需要二次检查，打开 Claude Desktop 开发者设置并查看 MCP 连接状态/日志

稳定运行时安装的位置：

• macOS: ~/Library/Application Support/Proton Mail Bridge MCP

• Linux: ~/.local/share/proton-mail-bridge-mcp

• Windows: %APPDATA%\Proton Mail Bridge MCP

🤖 它在 Claude Desktop 中是如何工作的

如果你已经打开了 Claude Desktop，首先需要知道这一点：

• Claude Desktop 也支持要求输入 URL 的远程连接器。

• 本项目不是那种连接器。

• 它在本地工作，因为 Proton Bridge 也在你的机器上本地工作。

• 因此，这里正确的设置是本地 Claude Desktop 安装流程，而不是远程 URL 框。

为什么这仍然有用：

• Gmail 目前拥有最原生的 Claude 体验

• Proton 用户还没有同样的官方路径

• 本项目现在就为 Claude Desktop 提供了实用的本地 Proton 集成

为什么没有远程 URL 可以粘贴：

• 远程 URL 连接器期望一个托管的 MCP 服务器

• 本项目期望在你的机器上访问 Proton Bridge

• Proton Bridge 通常在 127.0.0.1 上公开本地 IMAP/SMTP 访问

• 因此，最简单和最安全的设置是本地的，而不是远程的

这意味着当前版本中支持的 Claude Desktop 路径是：

• npm run setup:claude-desktop 用于引导式零手动配置流程

• npm run install:claude-desktop 用于高级或自动化的 Claude Desktop 安装

• npm run update:claude-desktop 在更新此仓库后刷新已安装的 Claude Desktop 运行时

• npm run doctor:claude-desktop 确认 Claude Desktop 仍然指向有效的 Proton Mail Bridge MCP 运行时

• CLAUDE-DESKTOP-PACKAGING.md 中记录的 .mcpb 本地扩展轨道

🖥️ CLI

你也可以直接从终端使用 Proton Mail Bridge MCP。

当你想要执行以下操作时，这很有用：

• 在不打开 Claude Desktop 的情况下测试 Proton Bridge

• 以更少的步骤运行快速搜索或读取

• 脚本化同步和诊断

• 在让 Claude 使用它之前验证本地邮件堆栈是否工作

• 直接从终端调用完整的 MCP 工具界面

CLI 二进制文件是：

proton-mail-bridge

或者，从仓库中：

npm run cli -- help

主要命令：

• proton-mail-bridge status

• proton-mail-bridge doctor

• proton-mail-bridge sync --folder INBOX --limit 150

• proton-mail-bridge search "label:inbox invoice"

• proton-mail-bridge search --live --from openai.com

• proton-mail-bridge read INBOX::25642

• proton-mail-bridge tools

• proton-mail-bridge tool get_connection_status

• proton-mail-bridge tool search_indexed_emails --args '{"query":"invoice","limit":3}'

• proton-mail-bridge claude check

• proton-mail-bridge claude install

大多数命令也支持 --json 以获取机器可读的输出。

实际示例：

# Check whether Proton Bridge and Claude-side wiring are healthy
proton-mail-bridge doctor --json

# Search indexed mail
proton-mail-bridge search "label:inbox invoice" --limit 10

# Read one message
proton-mail-bridge read INBOX::25642

# Call any MCP tool directly from Terminal
proton-mail-bridge tools
proton-mail-bridge tool get_connection_status --json
proton-mail-bridge tool search_indexed_emails --args '{"query":"invoice","limit":3}'

# Check Claude Desktop integration
proton-mail-bridge claude check --json

如果你希望 CLI 能够访问 MCP 服务器公开的所有内容，请使用：

proton-mail-bridge tools
proton-mail-bridge tool <tool-name> --args '{"key":"value"}'
proton-mail-bridge tool <tool-name> --args-file ./input.json

这为你提供了两种使用同一系统的方法：

• Claude Desktop 将其用作 MCP 服务器

• 终端将其用作 CLI，包括通用的 MCP 工具调用

针对 Bridge 用户的零手动配置路径

1. 在项目文件夹中打开终端。

2. 运行：

npm run setup:claude-desktop

3. 回答以下提示：

   • 你的 Proton Bridge 用户名

   • 你的 Proton Bridge 密码

   • 是否要使用标准的本地 Bridge 端口

   • 你希望本地数据存储在哪里

4. 重启 Claude Desktop。

5. 打开 Claude 并检查 Proton Mail Bridge MCP 工具是否可用。

这是最简单的路径，因为它避免了手动 JSON 编辑和手动环境变量设置。

如何验证它是否有效：

1. 打开 Claude Desktop。

2. 开始或打开一个聊天。

3. 点击消息框附近的 + 按钮。

4. 打开 Connectors。

5. 查找 proton-mail-bridge。

如果你能在那里看到它，Claude Desktop 就能看到这个 MCP 服务器。

这意味着它可以在这台电脑上用于正常的 Claude Desktop 使用，而不仅仅是在你运行设置的仓库文件夹内。

如果你以后想进行快速的终端检查，请运行：

npm run check:claude-desktop

该命令会告诉你：

• Claude Desktop 是否有 proton-mail-bridge 条目

• Claude Desktop 正在使用哪个运行时目录

• 运行时文件和依赖项是否存在

Mac 注意事项

在 macOS 上，Claude Desktop 运行时需要一个 macOS 原生的 better-sqlite3 二进制文件。

当前的安装程序现在会在暂存的 Claude Desktop 运行时中重新构建该原生模块，这避免了常见的 Linux 构建的二进制文件被复制到 Mac 设置中导致的不匹配问题。

如果你更换了机器、从其他环境恢复，或者稍后看到原生模块崩溃，通常的修复方法很简单：

npm run update:claude-desktop

这会刷新暂存的 Claude Desktop 运行时，并为当前机器重新构建原生 SQLite 模块。

npm run install:claude-desktop 的用途

npm run install:claude-desktop 是为 Claude Desktop 准备的。

更具体地说，它是将此 MCP 服务器注册到 Claude Desktop 中的高级安装程序。

它不会安装 Claude Desktop 本身。

它使用与设置向导相同的全机运行时方法。

在以下情况下使用它：

• 你想要一个可脚本化的安装

• 你已经管理了自己的 PROTONMAIL_* 环境变量

• 你不想使用交互式向导

高级本地安装

如果你更喜欢自己控制环境变量，或者想要更可脚本化的设置，请使用下面的安装程序命令。

首先，导出你的 Bridge 值：

export PROTONMAIL_USERNAME='your-address@proton.me'
export PROTONMAIL_PASSWORD='your-bridge-password'
export PROTONMAIL_IMAP_HOST='127.0.0.1'
export PROTONMAIL_IMAP_PORT='1143'
export PROTONMAIL_IMAP_SECURE='false'
export PROTONMAIL_SMTP_HOST='127.0.0.1'
export PROTONMAIL_SMTP_PORT='1025'
export PROTONMAIL_DATA_DIR="$HOME/.proton-mail-bridge-mcp"
export PROTONMAIL_AUTO_SYNC='true'
export PROTONMAIL_STARTUP_SYNC='true'
export PROTONMAIL_SYNC_INTERVAL_MINUTES='5'
export PROTONMAIL_IDLE_WATCH='true'
export PROTONMAIL_IDLE_MAX_SECONDS='30'
export PROTONMAIL_READ_ONLY='false'
export PROTONMAIL_ALLOW_SEND='true'
export PROTONMAIL_ALLOW_REMOTE_DRAFT_SYNC='true'
export PROTONMAIL_ALLOWED_ACTIONS='mark_read,mark_unread,star,unstar,archive,trash,restore'

然后运行：

npm run install:claude-desktop

该安装程序：

• 构建项目

• 写入 Claude Desktop MCP 条目

• 使用