  ____  ____   ___ _____ ___  _   _   __  __    _    ___ _
 |  _ \|  _ \ / _ \_   _/ _ \| \ | | |  \/  |  / \  |_ _| |
 | |_) | |_) | | | || || | | |  \| | | |\/| | / _ \  | || |
 |  __/|  _ <| |_| || || |_| | |\  | | |  | |/ ___ \ | || |___
 |_|   |_| \_\\___/ |_| \___/|_| \_| |_|  |_/_/   \_\___|_____|
  Bridge Client  ·  CLI + Claude Desktop MCP for Proton Mail

Proton Mail Bridge 客户端

proton-mail-bridge-client MCP 服务器

一个功能齐全的 Proton Mail CLI 和 Claude Desktop MCP，构建于 Proton Bridge 之上。

关于

Proton Mail Bridge 客户端为您提供了两种以编程方式使用 Proton Mail 的方法：

CLI — 一个与 MCP 界面完全对等的终端客户端。从命令行即可读取、搜索、发送、草拟、归档、管理文件夹、分类邮件线程并运行诊断。邮件正文可通过 stdin 管道传输。输出格式支持人类可读或 --json。

MCP 服务器 — 将相同的功能作为模型上下文协议 (MCP) 服务器公开，以便 Claude Desktop 可以在任何聊天中读取和管理您的 Proton Mail，前提是 Proton Bridge 正在同一台机器上运行。

这两个界面共享相同的后端：Proton Bridge IMAP 和 SMTP、本地 SQLite 索引以及审计日志。除了您自己的 Proton 账户外，没有托管中继、没有远程 URL，也不依赖云服务。

先决条件

Node.js 18+
已安装并登录 Proton Bridge
从 Bridge 获取：IMAP 主机/端口、SMTP 主机/端口、用户名、Bridge 密码

默认本地 Bridge 地址：IMAP 127.0.0.1:1143，SMTP 127.0.0.1:1025

安装

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

安装后，proton-mail-bridge-client（以及 proton-mail-bridge）二进制文件将可从仓库中获取。

进行系统级安装：npm install -g .

CLI

proton-mail-bridge-client <command> [options]

所有命令均支持 --json 以获取机器可读的输出。

读取

proton-mail-bridge-client emails --folder INBOX --limit 25
proton-mail-bridge-client read INBOX::25642
proton-mail-bridge-client search "invoice" --limit 10
proton-mail-bridge-client search --live --from openai.com
proton-mail-bridge-client attachments INBOX::25642

分类

proton-mail-bridge-client digest
proton-mail-bridge-client threads "quarterly review"
proton-mail-bridge-client actionable
proton-mail-bridge-client followups
proton-mail-bridge-client thread-brief <threadId>
proton-mail-bridge-client document-threads --category invoice
proton-mail-bridge-client meeting-context alice@example.com

撰写与发送

proton-mail-bridge-client send --to bob@example.com --subject "Hey" --body "Hello"
echo "Hello" | proton-mail-bridge-client send --to bob@example.com --subject "Hey"
proton-mail-bridge-client reply INBOX::25642 --body "On it."
proton-mail-bridge-client reply INBOX::25642 --reply-all --body "On it."
proton-mail-bridge-client forward INBOX::25642 --to carol@example.com

邮箱操作

proton-mail-bridge-client move INBOX::25642 Folders/Archive
proton-mail-bridge-client archive INBOX::25642
proton-mail-bridge-client trash INBOX::25642
proton-mail-bridge-client restore Trash::25642
proton-mail-bridge-client mark-read INBOX::25642
proton-mail-bridge-client mark-read INBOX::25642 --unread
proton-mail-bridge-client star INBOX::25642
proton-mail-bridge-client delete INBOX::25642
proton-mail-bridge-client batch archive INBOX::100,INBOX::101,INBOX::102
proton-mail-bridge-client thread-action <threadId> archive

文件夹

proton-mail-bridge-client folders
proton-mail-bridge-client create-folder Folders/Receipts
proton-mail-bridge-client rename-folder Folders/Receipts Folders/Bills
proton-mail-bridge-client delete-folder Folders/Bills

草稿

proton-mail-bridge-client drafts
proton-mail-bridge-client draft-create --to bob@example.com --subject "Draft" --body "..."
proton-mail-bridge-client draft-read <id>
proton-mail-bridge-client draft-update <id> --subject "Updated subject"
proton-mail-bridge-client draft-reply INBOX::25642 --body "Will do."
proton-mail-bridge-client draft-forward INBOX::25642 --to carol@example.com
proton-mail-bridge-client draft-sync <id>
proton-mail-bridge-client draft-send <id>
proton-mail-bridge-client draft-delete <id>
proton-mail-bridge-client remote-drafts

分析与诊断

proton-mail-bridge-client stats
proton-mail-bridge-client analytics
proton-mail-bridge-client contacts
proton-mail-bridge-client volume-trends --days 14
proton-mail-bridge-client watch --timeout 30
proton-mail-bridge-client test-email you@example.com
proton-mail-bridge-client doctor
proton-mail-bridge-client status
proton-mail-bridge-client sync --folder INBOX --limit 150

MCP 工具透传

任何 MCP 工具也可以直接从 CLI 调用：

proton-mail-bridge-client tools
proton-mail-bridge-client tool get_connection_status --json
proton-mail-bridge-client tool search_indexed_emails --args '{"query":"invoice","limit":3}'

环境

CLI 和 MCP 服务器读取相同的环境变量：

export PROTONMAIL_USERNAME='you@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-client"

通过文件或命令获取可选密钥（避免在 shell 中出现原始凭据）：

export PROTONMAIL_USERNAME_FILE='/path/to/user.txt'
export PROTONMAIL_PASSWORD_FILE='/path/to/pass.txt'
# or
export PROTONMAIL_USERNAME_COMMAND='pass proton/username'
export PROTONMAIL_PASSWORD_COMMAND='pass proton/password'

完整的运行时标志：

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'
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'

Claude Desktop 设置

要将 Proton Mail Bridge 客户端与 Claude Desktop 一起使用，请运行引导向导：

npm run setup:claude-desktop

这将：

检查您的本地 Bridge 端口
询问您的 Bridge 用户名和密码
构建项目
安装稳定的机器级运行时
写入 Claude Desktop MCP 配置条目

设置完成后：重启 Claude Desktop，保持 Proton Bridge 开启，然后检查 + → Connectors → proton-mail-bridge。

运行时安装在：

macOS: ~/Library/Application Support/Proton Mail Bridge Client
Linux: ~/.local/share/proton-mail-bridge-client
Windows: %APPDATA%\Proton Mail Bridge Client

更新

git pull
npm run update:claude-desktop

手动配置 Claude Desktop

{
  "mcpServers": {
    "proton-mail-bridge": {
      "command": "node",
      "args": ["/path/to/runtime/dist/index.js"],
      "cwd": "/path/to/runtime",
      "env": {
        "PROTONMAIL_USERNAME": "you@proton.me",
        "PROTONMAIL_PASSWORD": "your-bridge-password",
        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
        "PROTONMAIL_IMAP_PORT": "1143",
        "PROTONMAIL_IMAP_SECURE": "false",
        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
        "PROTONMAIL_SMTP_PORT": "1025"
      }
    }
  }
}

macOS 注意事项

在 macOS 上，better-sqlite3 必须是为当前机器构建的原生二进制文件。安装程序会自动处理此问题。如果您从其他环境恢复或看到原生模块崩溃，请运行 npm run update:claude-desktop。

信任与安全

完全在本地运行 — 无托管中继，无远程 URL。
仅通过您自己机器上的 Proton Bridge 与 Proton Mail 通信。
PROTONMAIL_READ_ONLY=true 禁用所有写入操作。
PROTONMAIL_ALLOW_SEND=false 禁用 SMTP 发送，而不影响其他写入操作。
PROTONMAIL_ALLOWED_ACTIONS 控制允许哪些邮箱变更操作。
batch_email_action 和 apply_thread_action 均支持 dryRun: true。
支持 *_FILE 和 *_COMMAND 密钥，因此原始凭据永远不会出现在配置或 shell 历史记录中。
系统文件夹（收件箱、已发送、垃圾箱、垃圾邮件、归档、所有邮件）受到保护，防止意外删除。

与 Claude 原生 Gmail 连接器的对比

功能	Gmail 连接器	Proton Mail Bridge 客户端
设置	第一方 OAuth	需要 Proton Bridge + 此客户端
搜索和读取	原生 Claude UX	IMAP + 本地索引
发送邮件	否	是
草稿工作流	更好的第一方 UX	完全控制，包括远程草稿同步
附件内容	有限	获取并保存
邮箱操作	有限	完全（星标、移动、归档、垃圾箱、恢复、删除、批量）
文件夹管理	否	是（创建、重命名、删除）
CLI 访问	否	与 MCP 完全对等
原始消息链接	更好	仅限 MCP 资源链接
原生线程/标签	Gmail 原生	从 IMAP 重构

工具界面

发送

send_email · send_test_email · reply_to_email · forward_email

草稿

create_draft · create_reply_draft · create_forward_draft · create_thread_reply_draft · list_drafts · list_remote_drafts · get_draft · update_draft · sync_draft_to_remote · send_draft · delete_draft

读取

get_emails · get_email_by_id · search_emails · list_attachments · get_attachment_content · save_attachments · save_attachment

分类

get_folders · sync_folders · get_labels · get_threads · get_thread_by_id · get_thread_brief · get_actionable_threads · get_inbox_digest · get_follow_up_candidates · find_document_threads · prepare_meeting_context

操作

mark_email_read · star_email · move_email · archive_email · trash_email · restore_email · delete_email · batch_email_action · apply_thread_action

文件夹管理

create_folder · rename_folder · delete_folder

分析

get_email_stats · get_email_analytics · get_contacts · get_volume_trends

诊断

get_connection_status · get_runtime_status · run_doctor · get_audit_logs · run_background_sync · wait_for_mailbox_changes · sync_emails · get_index_status · search_indexed_emails · clear_cache · clear_index · get_logs

操作说明

get_emails 和 search_emails 返回一个复合的 emailId — 请将其用于读取和操作。
本地索引位于 PROTONMAIL_DATA_DIR/mail-index.sqlite。
审计日志位于 PROTONMAIL_DATA_DIR/audit.log。
后台同步和 IMAP IDLE 保持索引更新，但取决于 Bridge 是否保持运行。
search_indexed_emails 支持 from:、to:、subject:、label:、domain: 快捷方式。
草稿同步是尽力而为的 — 即使远程同步失败，本地草稿也会始终保留。

许可证

MIT

Proton Mail Bridge MCP