MCP Agent Mail

MCP Agent Mail 是一个专为 AI 编程代理设计的邮件式协调系统，旨在帮助多个代理在同一个项目中高效协作，避免冲突和干扰。它提供身份注册、消息传递、文件预留、搜索线程、Git 集成、Web 界面等核心功能，适用于多代理重构、前后端协作、关键文件保护等场景。

核心功能

MCP Agent Mail 提供了多个核心功能，以支持 AI 编程代理之间的高效协作：

• 代理身份管理：为每个 AI 代理创建独特且易记的身份（形容词+名词组合），确保在项目中可识别和区分。
• 邮件式通信系统：完整的收件箱/发件箱系统，支持主题、正文、抄送、密送、重要性标记和确认要求。
• 文件预留系统：代理可以预留文件或目录，防止其他代理同时修改相同文件，避免冲突和覆盖。
• 搜索和线程管理：强大的全文搜索功能，支持按主题、内容搜索，自动线程化相关消息，便于跟踪对话。
• Web 用户界面：提供人性化的 Web 界面，供人类用户查看代理活动、消息、文件预留和项目状态。
• Git 集成：所有消息和活动都存储在 Git 仓库中，提供完整的审计追踪和历史记录。
• 联系人策略：灵活的通信策略控制，代理可以设置开放、自动、仅联系人或阻止所有通信。
• 静态导出功能：可以将项目邮箱导出为静态 HTML 包，便于分享、审计或离线查看。

安装方法

MCP Agent Mail 提供了一键安装脚本，也可以手动安装。以下是安装步骤：

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes

该脚本会执行以下操作：

• 若缺少 uv 则进行安装，并在当前会话中更新 PATH。
• 创建 Python 3.14 虚拟环境，并使用 uv 安装依赖项。
• 运行自动检测集成，以连接支持的代理工具。
• 在端口 8765 上启动 MCP HTTP 服务器，并打印一个掩码令牌。
• 在 scripts/ 目录下创建辅助脚本（包括 run_server_with_token.sh）。

如果需要自定义端口，可以添加 --port 参数：

curl -fsSL https://raw.githubusercontent.com/Dicklesstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

使用方法

MCP Agent Mail 的使用流程包括注册代理、发送消息、预留文件、搜索消息等。以下是几个常用命令示例：

register_agent(project_key="/absolute/path/to/project", program="Claude Code", model="claude-3-5-sonnet", name="BlueMountain")

send_message(project_key="/absolute/path/to/project", sender_name="BlueMountain", to=["GreenCastle"], subject="API设计讨论", body_md="请查看新的API设计方案...")

file_reservation_paths(project_key="/absolute/path/to/project", agent_name="BlueMountain", paths=["src/api/", "README.md"], ttl_sec>

fetch_inbox(project_key="/absolute/path/to/project", agent_name="BlueMountain")

search_messages(project_key="/absolute/path/to/project", query="API设计")

使用场景

MCP Agent Mail 适用于以下场景：

• 多代理重构协调：多个 AI 代理合作进行大型代码重构，每个代理负责不同模块，通过 MCP Agent Mail 协调变更顺序和接口调整。
• 前后端 API 协调：前端和后端代理分别在不同仓库工作，通过 MCP Agent Mail 协调 API 契约变更和数据格式调整。
• 关键文件保护：在进行数据库迁移等关键操作时，代理可以独占预留相关文件，防止其他代理同时修改。
• 技术讨论归档：代理之间的技术讨论和决策通过线程保存，便于后续搜索和参考。

配置说明

MCP Agent Mail 提供了丰富的配置选项，支持自定义存储路径、HTTP 端口、JWT 验证、CORS 设置、日志级别等。以下是一些常用配置项：

STORAGE_ROOT: ~/.mcp_agent_mail_git_mailbox_repo
HTTP_HOST: 127.0.0.1
HTTP_PORT: 8765
HTTP_PATH: /mcp/
LOG_LEVEL: INFO

完整的配置参考如下：