herdr-mcp

An MCP server that gives a coding agent control of a running Herdr terminal session: list workspaces, tabs, panes and agents, read pane output, prompt other agents, send keys, run commands, wait for state or output, and split or close panes.

It is a thin stdio bridge. Every tool shells out to the herdr CLI, which already speaks Herdr's socket API and answers with JSON envelopes. There is no daemon, no port, no config file, and no auth.

Requirements

• herdr installed and on PATH (or set HERDR_BIN to its full path).

• A running Herdr session. The server talks to whatever session the herdr CLI resolves from the environment (HERDR_SOCKET_PATH / HERDR_SESSION).

• Python 3.12+ and uv.

Related MCP server: HT MCP Server

Run

From a checkout:

uv run herdr-mcp

Straight from GitHub, no checkout:

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

The process serves MCP over stdio, so it prints nothing to stdout; logs go to stderr (HERDR_MCP_LOG_LEVEL=DEBUG for argv tracing).

Client configuration

Claude Code:

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

Generic mcpServers JSON (Claude Desktop, Cursor, Codex, and friends):

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

From a local checkout instead:

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

Tools

Pane ids look like w17:p1, tab ids like w17:t1, workspace ids like w17. Agent tools accept a pane id or an agent name. Every tool returns the parsed result object from the herdr JSON envelope; read_pane returns plain text.

Failures from the CLI (unknown pane, timeout, dead socket) come back as MCP tool errors carrying herdr's own error code and message, so the model can correct itself.

Security

No auth, no sandbox, local stdio only. Any client that can start this server can run arbitrary commands in your terminal panes and read everything on screen, including whatever an agent pane is displaying. Only wire it up to clients you trust on your own machine.

Environment

Everything else in the environment is passed through untouched, which is how the CLI finds the right session socket.

Development

uv sync
uv run pytest -q

Unit tests drive the server through the SDK's in-memory client against a stub herdr script, so they never touch a live session.