Skip to main content
Glama

herdr-mcp

An MCP server that exposes a running Herdr session to MCP clients such as Grok Bot, Claude Desktop, or any other app that speaks the protocol.

Herdr is a terminal workspace manager for coding agents. It organizes terminals into workspaces, tabs and panes, recognizes the agent running in each pane, and tracks whether it is idle, working, blocked on a dialog, or done. This server lets a desktop assistant see all of that and act on it: read what Claude Code or Codex is doing in your terminal, hand them a prompt, wait for them to finish, run commands in new panes, and react to lifecycle events as they happen.

How it works

  • Every control tool is a typed wrapper over the herdr CLI, so name resolution, --wait semantics and protocol compatibility stay Herdr's job.

  • A background event tap holds one events.subscribe connection open on Herdr's Unix socket. It buffers every event with a monotonic sequence number and subscribes to pane.agent_status_changed for each pane, resubscribing when new panes appear. Clients poll with events_recent or block with events_wait.

  • Mutating tools carry MCP annotations (readOnlyHint, destructiveHint) so clients can gate them with per-tool permissions.

Related MCP server: herdr-mcp

Requirements

  • Herdr 0.9 or newer, with a server running for the session you want to expose (start it with herdr or herdr server).

  • Python 3.12 or newer and uv.

Install

git clone https://github.com/frysquint/herdr-mcp.git ~/git/herdr-mcp
cd ~/git/herdr-mcp
uv sync
uv run herdr-mcp --help

uv sync creates .venv/bin/herdr-mcp, an absolute entry point that needs no shell setup. That is the path to hand to desktop clients, which often run with a minimal PATH.

Grok Bot

Open Grok Bot settings, go to MCP servers, add a server, and paste:

{
  "mcpServers": {
    "herdr": {
      "command": "/home/USER/git/herdr-mcp/.venv/bin/herdr-mcp",
      "args": []
    }
  }
}

Replace USER with your login. Grok Bot accepts one server per paste.

If you prefer to run through uv instead of the venv entry point:

{
  "mcpServers": {
    "herdr": {
      "command": "/absolute/path/to/uv",
      "args": ["run", "--project", "/home/USER/git/herdr-mcp", "herdr-mcp"]
    }
  }
}

Other MCP clients

Claude Desktop, Claude Code, Codex and most others take the same command/args shape. For Claude Code:

claude mcp add herdr -- /home/USER/git/herdr-mcp/.venv/bin/herdr-mcp

To serve over HTTP instead of stdio (for remote clients or several clients sharing one tap):

uv run herdr-mcp --transport streamable-http --host 127.0.0.1 --port 8765

The endpoint is http://127.0.0.1:8765/mcp. There is no authentication; keep it on loopback or put it behind something that authenticates.

Configuration

All configuration is through the environment of the server process.

Variable

Effect

HERDR_BIN_PATH

Path to the herdr binary. Default: first herdr on PATH.

HERDR_SESSION

Target a named Herdr session instead of the default one.

HERDR_SOCKET_PATH

Low-level override of the socket path (CLI and event tap).

HERDR_MCP_MACHINE

Run every command against a saved SSH machine profile (herdr --machine). Live events are disabled in this mode because there is no local socket for that machine.

HERDR_MCP_LOG_LEVEL

Log level written to stderr. Default INFO.

Tools

Read-only: herdr_status, session_snapshot, workspace_list, workspace_get, tab_list, pane_list, pane_get, pane_layout, pane_process_info, pane_read, pane_wait_output, agent_list, agent_get, agent_explain, agent_read, agent_wait, worktree_list, events_status, events_recent, events_wait.

Mutating: workspace_create, workspace_focus, workspace_rename, tab_create, tab_focus, tab_rename, pane_split, pane_run, pane_send_text, pane_send_keys, pane_rename, agent_prompt, agent_send_keys, agent_start, agent_rename, agent_focus, worktree_create, notification_show.

Destructive: workspace_close, tab_close, pane_close.

Event kinds

Broadcast events from Herdr, in underscore form: workspace_created, workspace_updated, workspace_metadata_updated, workspace_renamed, workspace_moved, workspace_reordered, workspace_closed, workspace_focused, worktree_created, worktree_opened, worktree_removed, tab_created, tab_closed, tab_focused, tab_renamed, tab_moved, pane_created, pane_closed, pane_updated, pane_focused, pane_moved, pane_exited, pane_agent_detected, layout_updated.

Per-pane subscription events: pane_agent_status_changed with agent_status one of idle, working, blocked, done, unknown.

Synthetic events from the tap itself: tap_connected, tap_disconnected, tap_events_lost. If you see tap_events_lost, re-read state with session_snapshot; Herdr does not replay missed events.

A typical delegation loop

  1. agent_list to find a ready agent (status idle or done).

  2. events_recent with limit: 0 to learn latest_seq.

  3. agent_prompt with wait: true, or send it with wait: false and then events_wait with since_seq, kinds: ["pane_agent_status_changed"], pane_id, and agent_status: ["done", "blocked", "idle"].

  4. agent_read to collect the response. If the status was blocked, show the user the dialog text before answering it with agent_send_keys.

Development

uv run pytest
uv run herdr-mcp --log-level DEBUG   # speaks MCP on stdin/stdout

The unit tests fake the herdr binary and do not need a running server.

License

MIT. See LICENSE.

Available Tools

41 tools
agent_explainB
Read-onlyIdempotent

Explain how Herdr detected an agent and why it reports its current state.

Inputs: target (required). Returns: object

agent_focusB

Switch the user's view to an agent's pane and mark its completion as seen.

Inputs: target (required). Returns: object

agent_getA
Read-onlyIdempotent

Get one agent by unique name or hosting pane id.

Inputs: target (required). Returns: object

agent_listA
Read-onlyIdempotent

List recognized coding agents: kind, name, pane, cwd, status and terminal title.

Inputs: no named parameters. Returns: object

agent_promptA

Submit a prompt to an agent. With wait=true, block until the agent settles (idle, done or blocked by default, or any state in until). Rejected with agent_blocked if the agent is already waiting at a dialog.

Inputs: text (required), target (required), wait, until, +1 more. Returns: object

agent_readA
Read-onlyIdempotent

Read an agent's terminal output. Use after agent_prompt to see the response; use source=detection for the raw bottom-of-screen text.

Inputs: target (required), ansi, lines, source. Returns: object

agent_renameA

Give an agent a unique name, or clear it when name is omitted.

Inputs: target (required), name. Returns: object

agent_send_keysB

Send logical key presses to an agent's UI, for example ["esc"], ["ctrl+c"], ["enter"], ["y"].

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

agent_startA

Start a coding agent (kind such as claude, codex, grok, opencode, pi) in an existing idle shell pane and name it. Extra args go to the agent's own CLI.

Inputs: kind (required), name (required), pane_id (required), args, +1 more. Returns: object

agent_waitB
Read-onlyIdempotent

Wait until an agent reaches a settled state (idle, done or blocked by default, or any state in until).

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

events_recentB
Read-onlyIdempotent

Buffered Herdr events after since_seq, newest last. Kinds include pane_agent_status_changed, pane_agent_detected, pane_created, pane_closed, pane_exited, tab_created, tab_closed, workspace_created, workspace_closed, layout_updated, tap_connected, tap_disconnected. Returns latest_seq to use as the next cursor.

Inputs: kinds, limit, pane_id, since_seq, +2 more. Returns: object

events_statusA
Read-onlyIdempotent

State of the live event tap: connection, buffer bounds (oldest_seq, latest_seq), and last known agent status per pane.

Inputs: no named parameters. Returns: object

events_waitA
Read-onlyIdempotent

Block until a matching event arrives after since_seq, or until timeout_ms. Typical: kinds=["pane_agent_status_changed"], agent_status=["done","blocked"]. Returns timed_out=true with no events when nothing matched.

Inputs: since_seq (required), kinds, limit, pane_id, +3 more. Returns: object

herdr_statusA
Read-onlyIdempotent

Check that Herdr is reachable and report server version plus event tap state.

Inputs: no named parameters. Returns: object

notification_showC

Show a toast inside the Herdr terminal UI.

Inputs: title (required), body, sound, position. Returns: object

pane_closeA
Destructive

Close a pane and kill its process. Only close panes you created or the user named.

Inputs: pane_id (required). Returns: object

pane_getB
Read-onlyIdempotent

Get one pane by id (for example "w1:p3").

Inputs: pane_id (required). Returns: object

pane_layoutB
Read-onlyIdempotent

Geometry of the tab containing a pane: rects and split tree. Use it to pick a split direction.

Inputs: pane_id (required). Returns: object

pane_listA
Read-onlyIdempotent

List panes with cwd, title, hosted agent and agent status, optionally within one workspace.

Inputs: workspace_id. Returns: object

pane_process_infoB
Read-onlyIdempotent

Foreground process and shell information for a pane.

Inputs: pane_id (required). Returns: object

pane_readB
Read-onlyIdempotent

Read terminal output from a pane. recent-unwrapped joins soft wraps and suits logs; visible is the rendered viewport.

Inputs: pane_id (required), ansi, lines, source. Returns: object

pane_renameB

Set a pane's label, or clear it when label is omitted.

Inputs: pane_id (required), label. Returns: object

pane_runB

Type a shell command into a pane and press Enter. The pane must be at an interactive shell prompt.

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

pane_send_keysC

Send logical key presses to a pane, for example ["ctrl+c"] or ["esc"] or ["enter"].

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

pane_send_textB

Send raw text to a pane without pressing Enter.

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

pane_splitA

Split a pane to create a new shell pane beside it. Returns the new pane under result.pane. Split wide panes right and tall panes down.

Inputs: pane_id (required), cwd, focus, ratio, +1 more. Returns: object

pane_wait_outputC
Read-onlyIdempotent

Block until pane output contains a literal substring (match) or a Rust regex (regex). Output that already exists matches immediately.

Inputs: pane_id (required), lines, match, regex, +2 more. Returns: object

session_snapshotA
Read-onlyIdempotent

Full live snapshot: workspaces, tabs, panes, agents, layouts and focus. Large; prefer the list tools for routine checks.

Inputs: no named parameters. Returns: object

tab_closeA
Destructive

Close a tab and every pane process in it. Only close tabs you created or the user named.

Inputs: tab_id (required). Returns: object

tab_createC

Create a tab with one shell pane. Returns the new tab and root_pane ids.

Inputs: cwd, focus, label, workspace_id. Returns: object

tab_focusB

Switch the user's view to a tab (for example "w1:t2").

Inputs: tab_id (required). Returns: object

tab_listA
Read-onlyIdempotent

List tabs, optionally within one workspace.

Inputs: workspace_id. Returns: object

tab_renameC

Rename a tab.

Inputs: label (required), tab_id (required). Returns: object

workspace_closeA
Destructive

Close a workspace and every pane process in it. Only close workspaces you created or the user named.

Inputs: workspace_id (required). Returns: object

workspace_createA

Create a workspace with one tab and one shell pane. Returns the new workspace, tab and root_pane ids.

Inputs: cwd, focus, label. Returns: object

workspace_focusC

Switch the user's view to a workspace.

Inputs: workspace_id (required). Returns: object

workspace_getB
Read-onlyIdempotent

Get one workspace by id (for example "w1").

Inputs: workspace_id (required). Returns: object

workspace_listA
Read-onlyIdempotent

List workspaces with their labels, tab/pane counts and aggregate agent status.

Inputs: no named parameters. Returns: object

workspace_renameC

Rename a workspace.

Inputs: label (required), workspace_id (required). Returns: object

worktree_createC

Create a git worktree and open it as a linked workspace.

Inputs: cwd, base, path, focus, +3 more. Returns: object

worktree_listB
Read-onlyIdempotent

List git worktrees known to a workspace or repository.

Inputs: cwd, workspace_id. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 41 tools

    Disambiguation4/5

    The set is strongly segmented by resource prefix (workspace_, tab_, pane_, agent_, events_, worktree_), and repeated actions such as list/get/create/close target explicit resources. The closest overlaps are pane_read vs agent_read and pane_send_keys vs agent_send_keys, plus the several input tools, but descriptions make the intended conditions clear.

    Naming Consistency5/5

    All names use snake_case with a resource/domain prefix, and nearly all are resource_action forms like workspace_list, pane_read, and agent_prompt. Exceptions such as herdr_status, session_snapshot, and events_status are readable status/snapshot nouns and do not break the overall convention.

    Tool Count2/5

    41 tools is heavy for any single MCP server; even though the terminal/workspace/agent domain is broad, many fine-grained pane/agent input, read, and wait variants could be consolidated or parameterized. The count exceeds the reasonable 3-15 range and sits in the 'too many' band.

    Completeness4/5

    Core lifecycle is covered: workspaces, tabs, and panes can be created, listed, renamed, focused, and closed; agents can be started, prompted, waited on, and read; events and worktrees have support. Gaps remain for pane_focus/resize, agent_stop, tab_get, and worktree_remove, though terminal access and close operations provide workarounds.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables coding agents to control and inspect a running Herdr terminal session, including listing workspaces, tabs, panes, and agents, reading pane output, prompting agents, sending keys and commands, waiting for output or state, and splitting or closing panes.
      14
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients to remotely control a running Herdr session: see agent status, arrange tabs and panes, start and prompt coding agents, and run worktree-isolated jobs over stdio or Streamable HTTP. Includes policy controls such as allowlists, read-only mode, disabled tools, and an audit log.
      32
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets MCP clients such as Claude Code, Cursor, and Claude.ai inspect and drive herdr workspaces, panes, and coding agents over a local socket, running either as a local stdio process or as an OAuth-protected HTTP endpoint published through a Cloudflare Tunnel. It exposes tools to create workspaces and tabs, split panes, start and prompt agents, read their output, and wait for results.
      MIT