herdr-mcp

MCP server that lets AI assistants orchestrate coding agents running in Herdr by wrapping its Unix-socket JSON-RPC API (~/.config/herdr/herdr.sock, newline-delimited JSON, verified against Herdr 0.7.1 / socket protocol 14).

Requirements

• A running Herdr server (the socket must exist; check with herdr agent list)

• Node.js ≥ 20

• macOS or Linux (the transport is a Unix domain socket)

Related MCP server: nvim-mcp

Build

git clone <this-repo> && cd herdr-mcp
npm ci
npm run build     # emits dist/

The server binary is then node /abs/path/to/herdr-mcp/dist/index.js. All examples below use that form; substitute your absolute path. To run from source instead (no build step), use npx tsx /abs/path/to/herdr-mcp/src/index.ts.

Set the HERDR_SOCKET environment variable if your socket is not at ~/.config/herdr/herdr.sock.

Installation

Claude Code

claude mcp add --scope user herdr -- node /abs/path/to/herdr-mcp/dist/index.js

(--scope user makes it available in every project; omit for project-local.) Verify with /mcp inside a session.

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), then restart the app:

{
  "mcpServers": {
    "herdr": {
      "command": "node",
      "args": ["/abs/path/to/herdr-mcp/dist/index.js"]
    }
  }
}

Cursor

Settings → MCP → Add server, or ~/.cursor/mcp.json (global) / .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "herdr": {
      "command": "node",
      "args": ["/abs/path/to/herdr-mcp/dist/index.js"]
    }
  }
}

VS Code (Copilot agent mode)

.vscode/mcp.json in a workspace, or run MCP: Add Server from the command palette:

{
  "servers": {
    "herdr": {
      "type": "stdio",
      "command": "node",
      "args": ["/abs/path/to/herdr-mcp/dist/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "herdr": {
      "command": "node",
      "args": ["/abs/path/to/herdr-mcp/dist/index.js"]
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.herdr]
command = "node"
args = ["/abs/path/to/herdr-mcp/dist/index.js"]

To pass a non-default socket path in any client, add an env block, e.g. "env": { "HERDR_SOCKET": "/run/user/1000/herdr.sock" }.

Tools

Herdr quirks the client absorbs (0.7.1): the server closes the connection after every reply, so requests are serialized through a queue with one transparent retry; pane.split / pane.resize act on the focused pane (edit_layout focuses the target tab and restores focus after); event subscriptions are per-pane.

Development

npm run dev      # run the server on stdio
npm run inspect  # MCP Inspector against the live server
npm run check    # biome lint + tsc + vitest

Layout: src/protocol.ts (wire types, zod schemas, guards) → src/connection.ts (one NDJSON connection: framing, id correlation, pushes) → src/herdr-client.ts (HerdrApi interface + reconnecting client; one dedicated connection per event subscription) → src/tools.ts (MCP tools against HerdrApi) → src/index.ts (stdio wiring).

Notes for extenders: Herdr 0.7.1 closes the connection after each reply — the client transparently retries once on a fresh connection (never for server-answered errors). Tool output is deliberately shaped (src/views.ts); don't dump raw socket JSON into Claude's context. Tools depend on the HerdrApi interface, so new tools are testable against the in-memory fake in test/tools.test.ts.