herdr-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@herdr-mcp List all panes and show what each agent is doing."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
herdrinstalled and onPATH(or setHERDR_BINto its full path).A running Herdr session. The server talks to whatever session the
herdrCLI 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-mcpStraight from GitHub, no checkout:
uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcpThe 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-mcpGeneric 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 with ids, labels, and aggregate agent status. |
| List tabs across the session. |
| List panes with ids, workspace, tab, cwd, title, agent status. |
| List panes running a detected agent, with kind and status. |
| Show one agent's current state. |
| Read pane output as text ( |
| Submit a prompt to an agent, optionally waiting until it settles. |
| Wait until an agent reaches idle/working/blocked/done/unknown. |
| Send literal text to a pane without Enter. |
| Send key presses, e.g. |
| Run a command in a pane (text + Enter). |
| Wait for a literal substring or Rust regex in pane output. |
| Split a pane right or down and return the new pane id. |
| 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 |
|
| Path to the herdr binary. |
|
| 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 -qUnit 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 toolsclose_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceEnables goose to control the Herdr terminal workspace manager, allowing AI agents to inspect and manipulate workspaces, tabs, panes, run commands, and manage agent states.3MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI agents to securely spawn, monitor, and control terminal sessions in Herdr, supporting background execution and authenticated access.2MIT
- AlicenseAqualityCmaintenanceEnables 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.8MIT