Proton Bridge MCP

= 25.9" />

proton-bridge-mcp

Give your AI agent access to ProtonMail.

一 主控程序 通过本地连接ProtonMail和AI代理的服务器 质子桥 IMAP守护进程。阅读、搜索、组织和管理您的加密电子邮件——所有这些都是通过模型上下文协议完成的。

______________________________________________________________________

目录

• 特性
• 先决条件
• 快速开始
• 其他用途
• 认证
• 配置参考
• MCP工具
• Claude桌面手动配置
• 安全
• 故障排除
• 发展
• 建筑
• 贡献
• 致谢
• 许可证

______________________________________________________________________

特性

• 19个MCP工具 用于阅读、搜索和组织电子邮件
• 三种运输方式 --STDIO、HTTP和HTTPS
• IMAP连接池 具有可配置的最小/最大连接和空闲排水定时器
• 批量操作 具有输入顺序稳定性和每项错误报告功能
• 审核日志记录 所有变异操作（JSONL）
• 克劳德桌面包装 通过 .mcpb 捆绑包
• 零外部服务 --直接连接到您当地的质子桥

先决条件

重要提示： 网桥邮箱密码为 _不_ 您的ProtonMail登录密码。Proton Bridge专门为IMAP访问生成一个单独的密码。

快速开始

最快的入门方法是安装预构建的 .mcpb Claude Desktop中的软件包。

1.安装Proton邮件桥

下载并安装 质子邮件桥 来自Proton。使用您的ProtonMail帐户登录，等待初始同步完成。

2.记下您的网桥邮箱密码

在Proton Bridge应用程序中，单击您的帐户并复制 邮箱密码这是一个由Bridge生成的密码 不 您的ProtonMail登录密码。

3.安装MCPB包

下载 proton-bridge-mcp.mcpb 从 并使用Claude Desktop打开它。安装程序将提示您配置两个必填字段：

所有其他设置（主机、端口、池大小、日志级别）都有合理的默认值，可以保持原样。

4.验证其是否有效

安装后，请Claude检查您的电子邮件。服务器运行在 STDIO模式 --Claude Desktop将其作为子进程启动，因此没有网络侦听器，也没有要管理的身份验证令牌。在幕后，克劳德将使用 verify_connectivity 该工具用于确认与质子桥的连接是否正常。

就这样 现在，您可以让Claude阅读、搜索和组织您的ProtonMail。

______________________________________________________________________

其他用途

除了MCPB快速启动之外，您还可以直接从本地构建运行服务器。它支持三种运输方式。

STDIO（默认）

最简单的模式是通过stdin/stdout进行通信。当没有提供传输标志时，这是默认设置，非常适合 克劳德桌面 以及作为子进程启动服务器的其他MCP客户端。

npm run build

node dist/index.js \
  --bridge-username your@protonmail.com \
  --bridge-password your-bridge-password

不需要身份验证令牌——进程边界 _是_ 安全边界。

超文本传输协议

使用承载令牌身份验证运行Fastify HTTP服务器。当MCP客户端通过网络连接时，或者当您想在多个会话中共享一台服务器时，请使用此选项。

node dist/index.js --http \
  --bridge-username your@protonmail.com \
  --bridge-password your-bridge-password \
  --mcp-auth-token your-secret-token

服务器正在监听 127.0.0.1:3000/mcp 默认情况下。每个HTTP会话都有自己的 McpServer 实例，而IMAP池是共享的。

超文本传输安全协议

与HTTP相同，但使用TLS。如果不提供证书/密钥路径，服务器 自动生成自签名证书 在启动时。

# Auto-generated self-signed cert
node dist/index.js --https \
  --bridge-username your@protonmail.com \
  --bridge-password your-bridge-password \
  --mcp-auth-token your-secret-token

# Custom certificate
node dist/index.js --https \
  --bridge-username your@protonmail.com \
  --bridge-password your-bridge-password \
  --mcp-auth-token your-secret-token \
  --https-cert /path/to/cert.pem \
  --https-key /path/to/key.pem

______________________________________________________________________

认证

使用MCPB包？ 安装程序为您处理凭据配置——只需在安装过程中输入您的ProtonMail地址和Bridge邮箱密码。以下详细信息适用于手动或高级配置。

网桥身份验证（IMAP）

所有传输模式都需要网桥凭据才能连接到Proton bridge的IMAP服务器：

这些总是需要的。密码是网桥生成的邮箱密码，而不是您的ProtonMail帐户密码。MCPB清单(manifest.json)根据您在安装过程中输入的值自动配置这些。

MCP身份验证（仅限HTTP/HTTPS）

HTTP和HTTPS模式需要Bearer令牌进行客户端身份验证。这是 STDIO模式不需要 （包括MCPB安装），因为过程边界提供了隔离。

客户端必须在每个请求中包含令牌：

Authorization: Bearer your-secret-token

OAuth 2.0（计划中）

OAuth 2.0支持计划作为未来的里程碑，但尚未实现。看 问题#7 用于跟踪。

______________________________________________________________________

配置参考

配置遵循以下优先级： CLI标志>环境变量>默认值.

所有环境变量都使用 PROTONMAIL_ 前缀。您可以将它们设置为 .env 文件（参见 .env.example).

桥架连接

连接池

HTTP/HTTPS服务器

操作日志

日志记录

效用

______________________________________________________________________

MCP工具

服务器公开了MCP客户端可以调用的19个工具。每个工具都有注释 readOnlyHint, destructiveHint，以及 openWorldHint 因此客户端可以呈现适当的确认提示和信任边界警告。

对于 全部文件 --包括输入模式、返回类型和示例JSON——请参阅 工具参考.

所有批处理操作都会保留结果中的输入顺序，并报告每个项目的成功/失败。

______________________________________________________________________

Claude桌面手动配置

如果您不想使用MCPB包（请参阅 快速开始)，您可以通过编辑Claude Desktop的配置文件手动配置它。

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "proton-bridge-mcp": {
      "command": "node",
      "args": [
        "/path/to/proton-bridge-mcp/dist/index.js",
        "--bridge-username", "your@protonmail.com",
        "--bridge-password", "your-bridge-password"
      ]
    }
  }
}

这使用STDIO模式。有关Claude Desktop的HTTP/HTTPS使用情况，请参阅 其他用途.

______________________________________________________________________

安全

此服务器处理电子邮件凭据并提供对您的私人邮箱的访问。认真对待这些预防措施。

尽可能选择STDIO

STDIO模式是本地使用的推荐传输方式，即使您的MCP客户端支持HTTP。在STDIO模式下，凭据永远不会离开进程边界——没有网络侦听器，没有可泄漏的身份验证令牌，进程本身之外也没有攻击面。

仅当您真正需要基于网络的访问时（例如，远程MCP客户端或共享一台服务器的多个客户端），才使用HTTP或HTTPS。

承载令牌安全（HTTP/HTTPS）

在HTTP或HTTPS模式下运行时：

• 生成一个强随机令牌 --至少32个字符。使用 openssl rand -hex 32 或密码管理器。
• 永远不要将令牌提交到版本控制中。 使用环境变量或 .env 文件（即 .gitignored
• HTTPS比HTTP更受欢迎。 普通HTTP在每次请求时以明文形式传输Bearer令牌。即使在 localhost，其他进程或浏览器扩展可能会拦截它。如果您不提供自签名证书，HTTPS模式会自动生成自签名证书——没有理由不使用它。
• 绑定到 127.0.0.1，不 0.0.0.0. 默认侦听地址为 127.0.0.1，这限制了对本地机器的访问。将此更改为 0.0.0.0 将服务器暴露给整个网络。

OAuth 2.0（尚未实现）

OAuth 2.0支持在 问题#7 但是 尚未实现在此之前，承载令牌身份验证是HTTP/HTTPS模式的唯一选择。不要假设OAuth可用。

环境变量和秘密

凭据可以通过CLI标志或环境变量传递。注意权衡：

对于生产用途，请考虑使用机密管理器或限制您的 .env 文件(chmod 600 .env).

防火墙建议

Proton Bridge公开IMAP（默认 1143)和SMTP（默认 1025)在本地主机上。虽然这些必然 127.0.0.1 默认情况下，最好的做法是 防火墙这些端口 为防止任何未经请求的访问：

macOS（pf）：

# Block external access to Bridge ports (add to /etc/pf.conf)
block in on ! lo0 proto tcp to any port { 1143, 1025 }

Linux（ufw）：

sudo ufw deny in on eth0 to any port 1143
sudo ufw deny in on eth0 to any port 1025

这确保了即使Bridge的侦听地址配置错误，也没有外部机器可以访问它。

审计日志

所有变异操作（移动、标记已读/未读）都记录在JSONL审计文件中 ~/.proton-bridge-mcp/audit.jsonl 默认情况下。定期查看此日志，以验证是否只发生了预期的操作：

tail -f ~/.proton-bridge-mcp/audit.jsonl | jq .

此服务器不做什么

• 确实如此 不 存储或缓存您的电子邮件——所有数据都是从质子桥实时获取的
• 确实如此 不 发送电子邮件（尚不支持SMTP）
• 确实如此 不 给家里打电话或联系任何外部服务
• 确实如此 不 修改网桥设置或您的ProtonMail帐户

______________________________________________________________________

故障排除

端口1143上的连接被拒绝

原因： 质子桥未运行或IMAP已禁用。

修复：

1. 启动Proton Mail Bridge并等待其完全启动
2. 检查状态指示灯是否显示绿色/“已连接”
3. 验证在网桥设置中启用了IMAP（单击您的帐户>检查IMAP切换）
4. 请您的MCP客户致电 verify_connectivity tool——它将报告连接是否成功以及往返延迟

认证失败

原因： 错误的密码或帐户需要在Bridge中重新验证。

修复：

1. 打开Proton Bridge并点击您的帐户
2. 如果出现提示，请重新登录
3. 复制 邮箱密码 （不是您的ProtonMail登录密码！）
4. 更新您的 .env 或带有新密码的CLI标志

陈旧或丢失的电子邮件

原因： Proton Bridge的本地同步数据库可能已过期或损坏。

修复：

1. 打开Proton Bridge，点击您的帐户，然后使用 修理 功能
2. 等待重新同步完成
3. 使用 drain_connections MCP工具强制新的IMAP连接

请参阅 桥梁维修指南 了解详细的分步说明。

桥梁倒塌或冻结

质子桥偶尔会变得没有反应，特别是在系统睡眠/唤醒周期或网络更改后。

修复：

1. 强制退出Bridge（macOS上的活动监视器，Windows上的任务管理器）
2. 重新启动网桥
3. 如果崩溃持续存在，请尝试 完全重置程序

“连接太多”错误

原因： 连接池最大值设置得高于网桥可以处理的值，或者过时的连接没有被释放。

修复：

1. 降低 --pool-max （试试看 3 而不是 5)
2. 使用 drain_connections 冲洗水池的工具
3. 重新启动MCP服务器

自签名证书警告

当使用 --https 在不提供证书的情况下，服务器会生成一个自签名证书。MCP客户端可能会对此发出警告。

修复： 通过以下方式提供适当的证书 --https-cert 和 --https-key，或将您的客户端配置为信任自签名证书。对于本地开发，自签名是可以的。

调试提示

• 增加日志的详细程度： --log-level debug （或 trace 为了获得最大的细节）
• 查看审核日志： tail -f ~/.proton-bridge-mcp/audit.jsonl | jq .
• MCP检验员测试： npm run inspector 启动交互式web UI
• 检查桥接日志： 质子桥有自己的日志——通过桥设置>日志找到它们

______________________________________________________________________

发展

设置

git clone https://github.com/grover/proton-bridge-mcp.git
cd proton-bridge-mcp
nvm use           # or volta, mise, asdf — picks up .nvmrc / volta pin
npm install
cp .env.example .env
# Fill in your bridge credentials in .env

脚本

使用MCP检查器进行调试

这 MCP检查员 为交互式测试工具提供web UI：

# HTTP mode
node dist/index.js --http \
  --bridge-username x --bridge-password y \
  --mcp-auth-token my-token &

npx @modelcontextprotocol/inspector http://127.0.0.1:3000/mcp
# Set the Authorization header to: Bearer my-token

查看审核日志

tail -f ~/.proton-bridge-mcp/audit.jsonl | jq .

项目结构

src/
  index.ts          Entry point — CLI parsing and transport dispatch
  config.ts         CLI flags, env vars, and config validation
  server.ts         MCP tool registration and handler logic
  stdio.ts          STDIO transport setup
  logger.ts         Pino app logger (stderr or file)
  bridge/
    imap.ts         ImapClient — all IMAP operations
    pool.ts         ImapConnectionPool with version-based drain
    audit.ts        JSONL audit logger for mutating operations
    decorators.ts   @Audited decorator
  types/
    config.ts       Config type definitions
    email.ts        Email, folder, and attachment types
  http/
    app.ts          Fastify HTTP/HTTPS app factory

代码规范

• 仅ESM --所有本地进口必须使用 .js 扩展(import { Foo } from './foo.js')
• TypeScript 6 和 exactOptionalPropertyTypes 严格模式
• @Audited 装饰器 在每一个公众 ImapClient 方法
• 第一批 --所有操作都接受数组并保留输入顺序
• 配置优先级 --CLI标志>环境变量>默认值

______________________________________________________________________

建筑

看 建筑.md 查看完整的设计细节。高层堆栈：

MCP Client (Claude, Inspector, etc.)
       |
  [ Transport Layer ]
  STDIO | HTTP | HTTPS (Fastify + Bearer auth)
       |
  [ MCP Server ]
  Tool registration, input validation (Zod)
       |
  [ ImapClient ]
  @Audited methods, batch grouping by mailbox
       |
  [ ImapConnectionPool ]
  Version-based drain, idle timers, min/max sizing
       |
  Proton Bridge IMAP (127.0.0.1:1143)

______________________________________________________________________

贡献

欢迎投稿！以下是如何开始：

1. 分叉和克隆 存储库
2. 创建要素分支 从 main:

   git checkout -b feat/your-feature

1. 进行更改 --遵循上述代码约定
2. 运行预提交检查表 每次提交前：

   npm install        # ensure lockfile is in sync
   npm run lint       # must pass with zero errors
   npm run build      # must compile clean
   npm ci             # verify lockfile consistency

1. 推送并打开PR 反对 main

CI与审核

每个PR运行三个并行检查： 棉绒, 构建，以及 测试。合并前必须通过这三项。

PR由维护人员审查和合并。这是一个附带项目——响应时间可能会有所不同，所以请耐心等待。高质量的贡献总是受到赞赏。

发布

发布是通过以下方式管理的 释放它.维护人员运行 npx release-it 在本地，它会更新版本、更新更新日志并推送标签。然后，CI会自动创建GitHub Release：

• proton-bridge-mcp.mcpb --已准备好安装Claude Desktop软件包
• proton-bridge-mcp-X.Y.Z-source.tar.gz --源代码存档
• npm --该包发布到 (npm install -g proton-bridge-mcp)

______________________________________________________________________

致谢

构建于

• 质子邮件桥 --使该项目成为可能的本地IMAP/SMTP网关。Proton Bridge在本地解密您的端到端加密ProtonMail，以便标准邮件客户端（和此MCP服务器）可以访问它。
• 模型上下文协议SDK --用于构建MCP服务器的TypeScript SDK
• ImapFlow --基于promise的Node.js现代IMAP客户端
• 快车 --支持HTTP/HTTPS传输的高性能HTTP框架
• 皮诺 --Node.js的超快速JSON记录器
• 指挥官.js --CLI参数解析
• 萨德 --MCP工具输入的TypeScript第一模式验证
• 邮件解析器 --电子邮件正文和附件的MIME消息解析
• TypeScript 6--本项目所使用的语言

创建于

• 克劳德代码 通过 Anthropic --人工智能辅助开发
• 克劳德 通过 Anthropic --设计、架构和代码生成
• Visual Studio Code --代码编辑器
• **** --源代码控制、CI/CD和协作

______________________________________________________________________

许可证

麻省理工学院 ©2026 Michael Fröhlich和 克劳德 通过 Anthropic

______________________________________________________________________

Proton、Proton Mail和Proton Mail Bridge是 宝腾股份公司。此项目不隶属于Proton AG，也不由Proton AG认可或赞助。它是一个独立的开源工具，与本地安装的Proton Mail Bridge应用程序接口。