/ 目录 / 演练场 / MCP Agent Mail
● 社区 Dicklesworthstone ⚡ 即开即用

MCP Agent Mail

作者 Dicklesworthstone · Dicklesworthstone/mcp_agent_mail

给你的 agent 舰队配上邮件——独立身份、收件箱、可搜索的会话线程,以及文件租约协调。从此多个 agent 不再互相踩脚。

MCP Agent Mail 是一个纯 HTTP 的 FastMCP 服务器,为每个 agent 提供稳定身份、收件箱/发件箱、哈希链审计日志和自愿文件锁定租约。专为同时在同一个 monorepo 上运行多个 Claude Code / Codex / Gemini CLI 实例的团队设计——补上了 3 个 agent 凌晨两点同时重构同一文件时缺失的协调层。

为什么要用

核心特性

实时演示

实际使用效果

mcp-agent-mail.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-agent-mail",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-agent-mail": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "http://127.0.0.1:8765/mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add mcp-agent-mail -- npx -y mcp-remote http://127.0.0.1:8765/mcp

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: MCP Agent Mail

在同一个 monorepo 上协调 3 个 Claude Code 会话,避免合并地狱

👤 并行运行多个 agent 会话的团队 ⏱ ~30 min intermediate

何时使用: 你按功能分支启动 agent,但它们总是抢同一批文件。

前置条件
  • 每个 agent 都能访问的 Docker 主机docker compose up --build 暴露 :8765 端口
  • 每个 agent 拥有唯一身份 — 首次调用 whoami 自动注册;将其固定在 CLAUDE.md 中
步骤
  1. 注册身份
    Use mcp-agent-mail. Register me as claude-feature-auth and list active leases.✓ 已复制
    → 身份已持久化;返回租约列表
  2. 编辑前先申请租约
    Before editing src/auth/*, take a 30-min lease and announce intent in the #refactor thread.✓ 已复制
    → 租约已授予;其他 agent 可见该消息
  3. 交接工作
    Done with the auth module. Release leases, post a summary to #refactor with the diff range.✓ 已复制
    → 租约已释放;会话线程已更新

结果: 三个 agent 在同一仓库完成并行工作,互不覆盖。

注意事项
  • 租约是建议性的——agent 仍可忽略它 — 在 CLAUDE.md 中加一条规则:「编辑前必须检查租约,先发布意图」
搭配使用: filesystem · github

在关联仓库间的 agent 之间交接工作

👤 同时管理前后端 agent 的开发者 ⏱ ~20 min intermediate

何时使用: 后端 agent 完成了 API 变更;前端 agent 需要适配。

步骤
  1. 发送
    From claude-backend: send claude-frontend a message titled 'New /v2/orders schema' with the OpenAPI diff.✓ 已复制
    → 消息已发送;前端 agent 的收件箱计数增加
  2. 接收
    From claude-frontend: read inbox, summarize new messages, propose component updates.✓ 已复制
    → 前端 agent 确认变更并开始工作

结果: agent 之间异步交接,无需你手动复制粘贴 prompt。

注意事项
  • 跨机器时身份混淆 — 将身份绑定到主机名,或使用较长的随机后缀

获取每条 agent 消息和租约的取证追踪记录

👤 运维团队 / 排查 agent 异常行为 ⏱ ~15 min intermediate

何时使用: 某个 agent 在凌晨 3 点做了奇怪的事,你需要还原当时谁和谁说了什么。

步骤
  1. 搜索
    Search messages between 02:00 and 04:00 mentioning 'database migration'.✓ 已复制
    → 返回带哈希锚点的条目
  2. 验证链完整性
    Verify the audit chain hasn't been tampered.✓ 已复制
    → 哈希链有效;未检测到篡改

结果: 可用于事后复盘的 agent 通信完整记录。

注意事项
  • 数据库无限增长 — 配置定期清理策略;每月归档到 S3
搭配使用: filesystem

组合

与其他 MCP 搭配,撬动十倍杠杆

mcp-agent-mail + filesystem

并行 agent 的「先申请租约再编辑」工作纪律

Before any filesystem.write, claim a lease via mcp-agent-mail.✓ 已复制
mcp-agent-mail + github

向其他 agent 订阅的会话线程发送 PR 通知

When my PR merges, post to #merged with the SHA and changed paths.✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
whoami (none) 任意 agent 的第一次调用 free
send_message to, subject, body, thread? 将工作移交给另一个 agent free
read_inbox since?, limit? 会话开始时——查看队列中的待处理消息 free
claim_lease path, ttl_min, reason 编辑其他 agent 可能修改的文件之前 free
release_lease lease_id 提交后 / 完成工作时 free
search_messages query, from?, to? 取证分析或重新找回上下文 free

成本与限制

运行它的成本

API 配额
自托管;受限于你的硬件资源
每次调用 Token 数
极低——每次协调调用约 50-200 token 额外开销
费用
免费(MIT 许可)
提示
运行成本极低;真正的节省来自避免了重复劳动的 agent 调用

安全

权限、密钥、影响范围

最小权限: Network access between agent host and mail server
凭据存储: 可选的 bearer token,通过环境变量配置
数据出站: 数据留在自己的基础设施上,不调用第三方服务
切勿授予: Public exposure without TLS + auth

故障排查

常见错误与修复

Connection refused on :8765

确认 Docker 容器已启动且端口已转发;检查 docker ps

验证: curl http://127.0.0.1:8765/health
Identity collision

在身份名后附加随机后缀,或绑定到主机名

Lease taken by stale agent

租约按 TTL 自动过期;缩短默认 TTL 或使用管理工具强制释放

替代方案

MCP Agent Mail 对比其他方案

替代方案何时用它替代权衡
Plain shared CLAUDE.md最多两个 agent、低并发场景无状态——依赖所有 agent 读取同一个文件
Git branches per agent需要强隔离合并成本随规模增长;无实时信号机制

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills