MCP Agent Mail

🚀 MCP Agent Mail

MCP Agent Mail 是一个专为编码代理设计的类邮件协调层，以仅支持 HTTP 的 FastMCP 服务器形式呈现。它为代理提供了易于记忆的身份、收件箱/发件箱、可搜索的消息历史记录，以及自愿的文件保留“租约”，以避免相互干扰。

🚀 快速开始

一键安装

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）。

若你想指定特定位置或选项，可添加如 --dir <path>、--project-dir <path>、--no-start、--start-only、--port <number> 或 --token <hex> 等标志。

若遇到端口冲突：可使用 --port 指定不同的端口（默认端口为 8765）：

# 自定义端口安装
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

# 或在安装后使用 CLI 命令
uv run python -m mcp_agent_mail.cli config set-port 9000

手动安装

克隆仓库，在 Python 3.14 虚拟环境中使用 uv 进行设置和安装（若没有 uv，需先进行安装），然后运行 scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh。这将自动为你安装的各种编码代理工具进行设置，并在端口 8765 上启动 MCP 服务器。若你日后想再次运行 MCP 服务器，只需运行 scripts/run_server_with_token.sh：

# 安装 uv（若尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# 克隆仓库
git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail

# 创建 Python 3.14 虚拟环境并安装依赖项
uv python install 3.14
uv venv -p 3.14
source .venv/bin/activate
uv sync

# 检测已安装的编码代理，进行集成，并在端口 8765 上启动 MCP 服务器
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh

# 之后，使用相同的令牌再次运行 MCP 服务器
scripts/run_server_with_token.sh

# 现在，只需在其他控制台中启动 Codex - CLI、Claude Code 或其他代理工具；它们应该可以使用邮件工具。以下是一段现成的文本，你可以添加到现有的 AGENTS.md 或 CLAUDE.md 文件末尾，以帮助你的代理更好地利用新工具。

# 安装后更改端口
uv run python -m mcp_agent_mail.cli config set-port 9000

✨ 主要特性

• 身份管理：为编码代理提供临时但持久的身份，便于识别和跟踪。
• 消息传递：支持发送和接收包含图像的 GitHub 风格 Markdown 消息，方便信息交流。
• 搜索与汇总：可对对话进行搜索、汇总和线程化管理，提高信息检索效率。
• 文件保留：允许代理声明对文件或文件通配符的保留租约，避免冲突。
• 目录查看：可查看活动代理、程序/模型和活动的目录，了解整体情况。

💻 使用示例

基础用法

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

高级用法

# 自定义端口安装
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

📚 详细文档

集成 Beads（依赖感知任务规划）

Beads 是一个轻量级任务规划器（bd CLI），它与 Agent Mail 互补，将状态和依赖关系集中管理，而 Agent Mail 负责消息传递、文件保留和审计跟踪。项目地址：steveyegge/beads

网页界面（面向人类的邮件查看器）

服务器提供了一个轻量级、服务器渲染的网页界面，供人类使用。你可以浏览项目、代理、收件箱、单个消息、附件、文件保留信息，并在支持 FTS5 时进行全文搜索（自动回退到 LIKE 查询）。

静态邮箱导出（共享和分发存档）

share 命令组可将项目的邮箱导出为一个便携式、只读的捆绑包，任何人都可以在浏览器中查看。这适用于审计人员、利益相关者或团队成员，他们可以在不启动完整 MCP Agent Mail 堆栈的情况下浏览线程、搜索历史记录或证明交付时间线。

🔧 技术细节

核心架构

• HTTP 服务器：仅支持 HTTP 的 FastMCP 服务器，采用可流式 HTTP 协议，不使用 SSE 和 STDIO。
• 持久化模型：采用双持久化模型，将人类可读的 Markdown 文件存储在每个项目的 Git 仓库中，同时使用 SQLite 进行快速搜索、目录查询和文件保留/租约管理。
• 查询方式：采用“目录/LDAP”风格的查询方式，为代理提供易于记忆的形容词 + 名词名称。
• 文件保留：提供咨询性的文件保留功能，可选择使用预提交钩子来强制执行。
• 资源层：提供方便的读取资源层，如 resource://inbox/{agent}。

数据模型（SQLite）

• projects(id, human_key, slug, created_at)
• agents(id, project_id, name, program, model, task_description, inception_ts, last_active_ts, attachments_policy, contact_policy)
• messages(id, project_id, sender_id, thread_id, subject, body_md, created_ts, importance, ack_required, attachments)
• message_recipients(message_id, agent_id, kind, read_ts, ack_ts)
• file_reservations(id, project_id, agent_id, path_pattern, exclusive, reason, created_ts, expires_ts, released_ts)
• agent_links(id, a_project_id, a_agent_id, b_project_id, b_agent_id, status, reason, created_ts, updated_ts, expires_ts)
• project_sibling_suggestions(id, project_a_id, project_b_id, score, status, rationale, created_ts, evaluated_ts, confirmed_ts, dismissed_ts)
• fts_messages(message_id UNINDEXED, subject, body) + 触发器用于增量更新

📄 许可证

文档中未提及相关信息。

📋 配置参考