herdr-mcp

一个 MCP 服务器，让编码代理能够控制正在运行的 Herdr 终端会话：列出工作区、标签页、窗格和代理，读取窗格输出，向其他代理发送提示，发送按键，运行命令，等待状态或输出，以及拆分或关闭窗格。

它是一个精简的 stdio 桥接层。每个工具都会转调 herdr CLI，而该 CLI 已经会使用 Herdr 的 socket API，并以 JSON 信封格式返回响应。没有守护进程、没有端口、没有配置文件，也没有身份验证。

要求

• 安装 herdr 并确保它在 PATH 中（或者用 HERDR_BIN 指定其完整路径）。

• 需要有一个正在运行的 Herdr 会话。服务器会与 herdr CLI 从环境中（HERDR_SOCKET_PATH / HERDR_SESSION）解析出的那个会话通信。

• Python 3.12+ 和 uv。

Related MCP server: HT MCP Server

运行

从本地检出目录运行：

uv run herdr-mcp

直接从 GitHub 运行，无需检出：

uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

该进程通过 stdio 提供 MCP 服务，所以它不会向 stdout 打印任何内容；日志会输出到 stderr（设置 HERDR_MCP_LOG_LEVEL=DEBUG 可跟踪 argv）。

客户端配置

Claude Code：

claude mcp add herdr -- uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

通用的 mcpServers JSON（Claude Desktop、Cursor、Codex 等）：

{
  "mcpServers": {
    "herdr": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/aelaguiz/herdr-mcp", "herdr-mcp"],
      "env": {}
    }
  }
}

改为从本地检出目录运行：

{
  "mcpServers": {
    "herdr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/herdr-mcp", "herdr-mcp"]
    }
  }
}

工具

窗格 ID 形如 w17:p1，标签页 ID 形如 w17:t1，工作区 ID 形如 w17。代理工具接受窗格 ID 或代理名称。每个工具都会返回 herdr JSON 信封中解析后的 result 对象；read_pane 返回纯文本。

CLI 返回的失败信息（未知窗格、超时、socket 失效）会作为 MCP 工具错误返回，其中包含 herdr 自己的错误码和错误消息，因此模型可以自我纠正。

安全

没有身份验证、没有沙箱、仅本地 stdio。任何能启动这个办公户端的都可以在你的终端窗格中运行任意命令，并读取屏幕上的所有内容，包括某个 agent 窗格正在显示的任何东西。请只把把服务器连接到你自己机器上信任的客户端。

环境变量

环境中的其余所有内容都会原样传递，这正是 CLI 查找正确会话 socket 的方式。

开发

uv sync
uv run pytest -q

单元测试通过 SDK 的内存客户端并针对一个桩（stub）herdr 脚本来驱动服务器，不会接触真实会话。