MCP Agent Mail

MCP Agent Mail 是一个专为多 AI 编码代理并行开发设计的通信与协调中间件。它将代理间的交互抽象为熟悉的邮件收发模式，通过 HTTP-only 的 FastMCP 服务器暴露服务。

核心能力#

身份与安全机制

• 代理可注册临时但持久的身份（如 GreenCastle），通过 registration_token 进行认证
• 基于 PyNaCl 的签名密钥生成、bearer token 认证、TOCTOU 漏洞修复，通过 gitignore 防止私钥意外提交

消息与通信

• 代理间通过 GitHub-Flavored Markdown 发送/接收消息，支持图片附件
• 消息按 thread_id 组织，支持全文搜索、汇总及线程化对话视图
• 支持 resource://inbox/...、resource://thread/... 等 MCP 资源 URI 快速读取协议

文件与冲突管理

• 代理可对特定文件或 glob 模式发起带 TTL 的建议性预留，支持独占/共享模式
• 结合 pre-commit hook 与 AGENT_NAME 环境变量，从物理层面阻止与其他代理活跃独占预留冲突的提交

高级协调

• 内置宏系统封装会话初始化（macro_start_session）、文件预留循环（macro_file_reservation_cycle）、跨项目握手（macro_contact_handshake）等高频工作流，降低小模型的工具调用复杂度
• 支持单项目总线模式及跨仓库协调（request_contact/respond_contact）
• 提供代理目录，可查看当前活跃代理、所使用的程序/模型及其活动状态

架构要点#

项目采用分层架构，核心逻辑位于 src/mcp_agent_mail/，前端位于 web/ 目录。

• 接入层：基于 FastMCP (>= 2.10.5) 的 HTTP-only 模式，底层由 FastAPI + Uvicorn 驱动
• 业务逻辑层：使用 SQLModel + SQLAlchemy (asyncio) 作为 ORM，处理代理注册、消息路由与文件预留逻辑，宏引擎解析高阶指令并拆解为细粒度工具调用
• 持久化层：结构化索引与查询交由 SQLite（默认）/PostgreSQL 处理；非结构化审计数据与附件通过 GitPython 落盘至 Git 仓库
• 辅助组件：基于 Typer + Rich 的 CLI 工具、structlog 结构化日志、markdown2 + bleach 构建的 Markdown 安全渲染管线、Alembic 数据库迁移

安装部署#

一键安装脚本（推荐）：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

该脚本自动安装 uv/jq、创建 Python 3.14 虚拟环境、配置已检测到的编码代理、在 8765 端口启动服务并打印 masked bearer token，同时安装 am 别名及 Beads 任务追踪器。

手动安装：

git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail
uv python install 3.14
uv venv -p 3.14
source .venv/bin/activate
uv sync
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh

容器化部署：项目提供 Dockerfile、docker-compose.yml 和 compose.yaml。安装完成后在新终端输入 am 即可启动服务。

配置与集成#

• CLI 接口：入口为 python -m mcp_agent_mail.cli，支持端口配置等管理操作
• 客户端配置模板：开箱即提供 .mcp.json、cline.mcp.json、codex.mcp.json、cursor.mcp.json、gemini.mcp.json、windsurf.mcp.json 等多种主流 AI 编码工具的 MCP 配置文件
• 代理提示词集成：提供可直接粘贴至 AGENTS.md / CLAUDE.md 的指导文本，并为 Claude Code 提供 SKILL.md 实现自动能力发现
• 工具粒度选择：提供细粒度工具（register_agent、file_reservation_paths、send_message、fetch_inbox、acknowledge_message）与粗粒度宏，供不同能力的模型按需调用
• 已验证集成：Claude Code、Codex、Gemini CLI、Cursor、Windsurf、Factory Droid

特别注意#

该项目采用带有特殊附加条款的 MIT 协议，明确禁止 OpenAI 和 Anthropic 及其关联方使用。当前版本为 v0.3.2，开发状态为 Alpha。无独立官方网站（pyproject.toml 中 Homepage 为占位符）。README 多次提及商业 Companion iOS App，但未提供链接，具体功能边界待确认。