内容
# Proton Mail 桥接 + 流媒体 MCP 服务器
一个独立的 Docker Compose 堆栈：
1. 从源代码构建 **官方 [Proton Mail 桥接](https://github.com/ProtonMail/proton-bridge)** 并以 **无界面模式** (`--noninteractive`) 运行，通过本地 IMAP/SMTP 暴露您的 Proton Mail 账户。
2. 运行一个 **Python + FastMCP MCP 服务器**，通过 **流媒体 HTTP** 和 **Bearer Token 认证**，暴露完整的邮件读取和写入工具。
```
MCP 客户端 ──HTTP + Bearer──▶ mcp-server ──IMAP 1143 / SMTP 1025 (STARTTLS)──▶ protonmail-bridge ──▶ Proton
127.0.0.1:8080 （私有 "mailnet" 网络）
```
MCP 端点仅在 `127.0.0.1:8080` 上发布。在环回/LAN 上，纯 HTTP 上的 Bearer Token 是可接受的。
## 前置条件
- Docker + Docker Compose
- 付费 Proton Mail 账户（桥接需要 Mail Plus / Unlimited / Business）
## 设置
### 1. 配置环境
```bash
cp .env.example .env
# 生成一个强壮的 MCP Token：
openssl rand -hex 32 # 粘贴到 .env 中的 MCP_BEARER_TOKEN
```
### 2. 构建镜像
```bash
docker compose build
```
这会从 `docker-compose.yml` 中固定的标签 (`BRIDGE_TAG`) 编译官方桥接 (`make build-nogui`, Go 1.26)，并将其修补为绑定到 `0.0.0.0`，以便 MCP 容器可以访问它。
### 3. 登录 Proton 桥接（一次性，交互式）
```bash
docker compose run --rm protonmail-bridge bridge --cli
```
在提示符下：
```
>>> login # 输入您的 Proton 电子邮件、密码和 2FA
>>> info # 复制显示的 IMAP/SMTP 用户名和密码
>>> exit
```
入口点在 CLI 启动前自动设置 gpg/`pass` 密钥链。登录信息存储在 `protonmail` 卷中，并可以在重启后生存。
将 `info` 中的凭证放入 `.env`：
```
BRIDGE_USERNAME=<info 中的用户名>
BRIDGE_PASSWORD=<info 中的密码>
```
### 4. 启动堆栈
```bash
docker compose up -d
docker compose logs -f # bridge: IMAP/SMTP 在 0.0.0.0; mcp-server: 在 :8080 上提供服务
```
## 使用 MCP 服务器
端点：`http://127.0.0.1:8080/mcp/` — 发送 `Authorization: Bearer <MCP_BEARER_TOKEN>`。
使用 MCP 检视器快速检查：
```bash
npx @modelcontextprotocol/inspector
# 传输：流媒体 HTTP
# URL： http://127.0.0.1:8080/mcp/
# 头部： Authorization: Bearer <您的 MCP_BEARER_TOKEN>
```
### 示例：Claude 代码 / MCP 客户端配置
```json
{
"mcpServers": {
"protonmail": {
"type": "http",
"url": "http://127.0.0.1:8080/mcp/",
"headers": { "Authorization": "Bearer <您的 MCP_BEARER_TOKEN>" }
}
}
}
```
## 工具
| 工具 | 目的 |
| --- | --- |
| `list_folders` | 列出所有文件夹/标签 |
| `search_messages` | 搜索文件夹（自由文本 `query`，`unseen_only`，`limit`）；返回带有 `uid` 的摘要 |
| `get_message` | 完整消息：文本，HTML，头部，附件列表 |
| `get_attachment` | 一个附件的字节作为 base64 |
| `send_message` | 发送新邮件（至/cc/bcc，HTML，附件） |
| `reply_message` | 回复（保留线程；`reply_all`） |
| `forward_message` | 转发至新收件人 |
| `mark_read` | 标记已读/未读 |
| `flag_message` | 加星/标记或取消标记 |
| `move_message` | 移动到另一个文件夹 |
| `delete_message` | 删除消息 |
## 注意
- **凭证轮换：** 重新运行桥接登录会重新生成 IMAP/SMTP 密码。更新 `.env` 和 `docker compose up -d --force-recreate mcp-server`。
- **自签名 TLS：** 桥接在其本地 STARTTLS 端口上使用自签名证书；MCP 服务器故意跳过此私有链接的验证。
- **升级桥接：** 更改 `docker-compose.yml` 中的 `BRIDGE_TAG` 和 `docker compose build --no-cache protonmail-bridge`。
- `.env` 持有真实的秘密，并被 gitignore。
