Skip to main content
Glama
herdr-mcp

herdr-mcp

by aelaguiz

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: goose-herdr

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.

Tool

What it does

list_workspaces

List workspaces with ids, labels, and aggregate agent status.

list_tabs

List tabs across the session.

list_panes

List panes with ids, workspace, tab, cwd, title, agent status.

list_agents

List panes running a detected agent, with kind and status.

get_agent

Show one agent's current state.

read_pane

Read pane output as text (source: visible, recent, recent-unwrapped, detection).

prompt_agent

Submit a prompt to an agent, optionally waiting until it settles.

wait_agent

Wait until an agent reaches idle/working/blocked/done/unknown.

send_text

Send literal text to a pane without Enter.

send_keys

Send key presses, e.g. ["ctrl-c"], ["esc"], ["enter"].

run_command

Run a command in a pane (text + Enter).

wait_for_output

Wait for a literal substring or Rust regex in pane output.

split_pane

Split a pane right or down and return the new pane id.

close_pane

Close a pane and whatever is running in it.

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

Variable

Default

Meaning

HERDR_BIN

herdr

Path to the herdr binary.

HERDR_MCP_LOG_LEVEL

WARNING

Python log level (stderr).

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.

Available Tools

14 tools
close_paneA

Close a pane and any process running in it. pane: pane id like w17:p1.

Inputs: pane (required). Returns: object

get_agentA

Show one agent's current state.

target: a pane id like `w17:p1` or an agent name; get them from list_agents.

Inputs: target (required). Returns: object

list_agentsA

List panes running a detected coding agent, with agent kind and status.

Status is one of idle, working, blocked, done, unknown. Agents are addressed
by pane id (`w17:p1`) or by their agent name.

Inputs: no named parameters. Returns: object

list_panesA

List every pane with its id, workspace, tab, cwd, title, and agent status.

Pane ids look like `w17:p1` and are the target of every pane tool.

Inputs: no named parameters. Returns: object

list_tabsA

List tabs across the session. Tab ids look like w17:t1.

Inputs: no named parameters. Returns: object

list_workspacesA

List Herdr workspaces with their ids, labels, and aggregate agent status.

Workspace ids look like `w17`. Start here to orient in the session.

Inputs: no named parameters. Returns: object

prompt_agentA

Submit a prompt to an agent pane (types the text and submits it).

target: pane id like `w17:p1` or an agent name; see list_agents.
wait: also wait for the agent to settle (idle, done, or blocked) afterwards.
timeout_ms: only used with wait=True; the call fails if nothing matches in time.

Inputs: text (required), target (required), wait, timeout_ms. Returns: object

read_paneA

Read a pane's terminal output as plain text.

pane: pane id like `w17:p1` (see list_panes / list_agents).
lines: keep only the last N lines of the snapshot.
source: visible (what the user sees), recent (default scrollback tail),
recent-unwrapped (recent without soft wrapping), detection (bottom buffer
used for agent detection).
Note: herdr may return an empty string for source=recent with lines set on
panes with short scrollback; if that happens, retry without lines or with
source="visible".

Inputs: pane (required), lines, source. Returns: result

run_commandA

Run a shell command in a pane (sends the command text and Enter).

pane: pane id like `w17:p1`.
command: argv-style words, e.g. ["git", "status"]. This does not wait for the
command to finish; use wait_for_output or read_pane afterwards.

Inputs: pane (required), command (required). Returns: object

send_keysA

Send key presses to a pane, e.g. ["enter"], ["esc"], ["ctrl-c"].

pane: pane id like `w17:p1`. Keys are sent in order; use `esc` for Escape.

Inputs: keys (required), pane (required). Returns: object

send_textA

Send literal text to a pane without pressing Enter.

pane: pane id like `w17:p1`. Use run_command to send a command and Enter.

Inputs: pane (required), text (required). Returns: object

split_paneA

Split a pane and return the new pane's id.

pane: pane id like `w17:p1` to split.
direction: right or down.
ratio: fraction of the split given to the new pane, between 0 and 1.

Inputs: pane (required), ratio, direction. Returns: object

wait_agentA

Wait until an agent reaches one of the requested states.

target: pane id like `w17:p1` or an agent name.
until: any of idle, working, blocked, done, unknown. Default: idle, done, blocked.
timeout_ms: the call fails if no requested state is observed in time.

Inputs: target (required), until, timeout_ms. Returns: object

wait_for_outputA

Wait until a pane's output matches a pattern.

pane: pane id like `w17:p1`.
pattern: literal substring, or a Rust regular expression when regex=True.
The existing snapshot is searched first, then polled until timeout_ms.
source: visible, recent (default), or recent-unwrapped.

Inputs: pane (required), pattern (required), regex, source, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools have clearly distinct resource/action pairs (list_panes, list_agents, split_pane, close_pane, wait_agent, wait_for_output). The main ambiguity is among send_text, send_keys, run_command, and prompt_agent, since all deliver input to a pane; the descriptions largely clarify them, but an agent could still misselect send_text vs run_command or prompt_agent when composing an action.

    Naming Consistency5/5

    Almost every tool follows a clear verb_noun pattern: list_*, get_agent, prompt_agent, wait_agent, send_text, send_keys, run_command, split_pane, close_pane. The plural/singular list_* vs get_ is conventional and predictable, and there are no mixed casing or random names.

    Tool Count5/5

    14 tools is a well-scoped number for a terminal/agent-orchestration server. Each tool covers a meaningful operation without excessive redundancy or an overwhelming surface.

    Completeness4/5

    The surface covers orientation, reading output, sending input and keys, running commands, waiting for output/agent state, splitting panes, and closing panes—so core workflows are solid. The main gap is that there is no explicit way to create a new workspace or tab, only split an existing pane, which limits some session-management scenarios.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to orchestrate Herdr coding agents by wrapping its Unix-socket JSON-RPC API, providing tools for agent management, layout editing, and terminal interaction.
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables goose to control the Herdr terminal workspace manager, allowing AI agents to inspect and manipulate workspaces, tabs, panes, run commands, and manage agent states.
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables assistants to monitor and control AI coding agents via the herdr CLI, listing agents and reading their output, then optionally starting agents, sending prompts or keystrokes, and managing panes and tabs. Read-only tools are always available while write tools require explicit opt-in, and remote machines can be targeted.
      8
      MIT