proton-mcp

一个面向 Proton Mail 的自托管 Model Context Protocol（MCP）服务器，设计为与 Proton Mail Bridge 一同运行，并向 MCP 客户端暴露一组小巧且可审计的邮箱工具。

状态： 早期开发阶段。v0.1 刻意设计为只读。

目标

• 借助 Docker Compose 在 NAS 或家用服务器上持续运行。

• 让 Proton Mail Bridge 与局域网及互联网完全隔离。

• 通过本地 IMAP/SMTP 与 Bridge 通信，而不是直接处理 Proton 加密。

• 只暴露职责单一、范围受限的 MCP 工具，而不是通用的 Shell 或文件系统访问能力。

• 先返回邮件元数据、仅在按需时才返回完整正文，使邮箱清理更加高效。

• 只有在只读接口经过充分测试后，才加入受控的写操作。

Related MCP server: proton-mail-mcp

计划中的 v0.1 工具

• list_folders

• mailbox_stats

• top_senders

• search_mail

• get_message

工具契约见 docs/SPEC.md，部署模型见 ARCHITECTURE.md。

部署模型

MCP client
    |
    | authenticated MCP
    v
proton-mcp container
    |
    | localhost IMAP
    v
proton-bridge container
    |
    v
Proton Mail

预期的 Docker Compose 部署方案会让 proton-mcp 与 proton-bridge 共享同一个网络命名空间，届时 Bridge 仍可只绑定在 loopback 上。IMAP/SMTP 端口严禁发布到局域网。

开发原则

• 仓库、镜像、日志以及常规环境变量中均不存放 Proton 账户密码。

• 不提供可执行任意 shell 命令的 MCP 工具。

• v0.1 中不包含任何具有破坏性的 MCP 工具。

• 更倾向确定性的邮箱处理流程，而不是把大量邮件正文交给 LLM。

• 保持验证方式简单：未来的智能代理在收尾前应只需运行一条命令（make check）。

文档

• AGENTS.md — 为编码智能代理提供的简洁指引。

• ARCHITECTURE.md — 系统边界与架构决策。

• SECURITY.md — 安全不变量。

• docs/SPEC.md — MCP 工具契约。

• docs/DEVELOPMENT.md — 本地开发工作流。

• docs/OPERATIONS.md — Synology / Docker 运维指南。

许可证

MIT，参见 LICENSE。