herdr-grok-bridge

Unofficial read-only MCP bridge from Grok Bot (or any MCP stdio client) to a running Herdr session.

This project is not affiliated with Herdr. It offers MCP tools only — not an embedded native Herdr UI, Canvas, or refresh button.

What it does

Strict allowlist of three read operations (plus a non-sensitive bridge_info):

Not included (hard-denied): prompts, send-keys, focus, start/attach, pane run/close/split, generic RPC/shell, or any user-supplied executable command.

Read targets must be live pane_id values from list_agents (for example w1:p2). Bare kinds such as claude are rejected.

Related MCP server: remote-observer-mcp

Security risks

• Read access can reveal terminal secrets (tokens, passwords, private keys scrolled into a pane). Output is best-effort redacted and size-limited, but redaction is not perfect.

• Prefer Tailscale / SSH Host aliases and existing known_hosts entries.

• The bridge never changes focus, prompts agents, or restarts Herdr — but a compromised MCP client can still read whatever is visible in panes you expose.

Requirements

• Python 3.12+

• A reachable Herdr CLI (herdr) on the Herdr host (verified conceptually against Herdr 0.8.x / local-only socket; this bridge talks to the CLI, not the Unix socket directly)

• For remote use: OpenSSH client, BatchMode key auth, host key already in known_hosts

Install

From a release artifact (no git checkout)

python3 -m venv ~/.venvs/herdr-grok-bridge
~/.venvs/herdr-grok-bridge/bin/pip install /path/to/herdr_grok_bridge-0.1.2-py3-none-any.whl
# or: pip install /path/to/herdr_grok_bridge-0.1.2.tar.gz

Entry point: ~/.venvs/herdr-grok-bridge/bin/herdr-grok-bridge

From source with uv

uv sync
uv run herdr-grok-bridge --help

Deployment

A) Local (MCP server on the Herdr host)

{
  "mcpServers": {
    "herdr-readonly": {
      "command": "/home/USER/.venvs/herdr-grok-bridge/bin/herdr-grok-bridge",
      "args": [],
      "env": {
        "HERDR_BRIDGE_MODE": "local"
      }
    }
  }
}

B) SSH / Tailscale from Grok Bot’s Linux box (recommended remote path)

Configure OpenSSH so a Host alias already works non-interactively (ssh herdr-box herdr agent list). Then:

{
  "mcpServers": {
    "herdr-readonly": {
      "command": "/home/USER/.venvs/herdr-grok-bridge/bin/herdr-grok-bridge",
      "args": [],
      "env": {
        "HERDR_BRIDGE_MODE": "ssh",
        "HERDR_BRIDGE_SSH_HOST": "herdr-box"
      }
    }
  }
}

herdr-box is a generic example Host alias — use your own. Do not put private hostnames, IPs, or credentials in this repository.

SSH argv is fixed by the bridge (not tool-callable):

• BatchMode=yes

• StrictHostKeyChecking=yes (existing known_hosts only)

• PasswordAuthentication=no / KbdInteractiveAuthentication=no

• optional HERDR_BRIDGE_SSH_USER, HERDR_BRIDGE_SSH_PORT, HERDR_BRIDGE_SSH_IDENTITY_FILE

Remote shape: ssh … <destination> -- herdr <allowlisted args…>

Environment reference

Compatibility notes

• Herdr 0.8.0 rejects agent list|get --format json and already prints JSON by default. The bridge calls those commands without --format json first, then retries once with the flag only if the default path fails with a CLI/JSON error (newer CLIs that require the flag).

• list_agents expects JSON shaped like { "id": "cli:agent:list", "result": { "type": "agent_list", "agents": [ … ] } }.

• Some Herdr versions reject --lines with --source visible / detection. This bridge omits --lines for those sources and truncates client-side when requested.

• For recent / recent-unwrapped, a capped --lines is always sent (default 80).

Error signaling (MCP isError)

Validation failures, Herdr CLI failures, timeouts, and SSH/transport errors return a normal tools/call result with:

{ "content": [{ "type": "text", "text": "…" }], "isError": true }

Clients must inspect isError / CallToolResult.is_error. Do not classify success vs failure by scraping the text body.

Unknown tools (including any mutating name such as agent_prompt / pane_run): not registered on this server. The official MCP Python SDK rejects them with isError: true and message Unknown tool: … without invoking our runner — so no Herdr/SSH command runs.

Development

uv sync --group dev
uv run pytest
uv build   # wheel + sdist under dist/

Unit tests are mock-backed: command construction, validation, timeouts, JSON decoding, mutation denial, and an in-memory MCP init/list/call smoke test. They do not touch a live Herdr host.

License

MIT. Wholly new code for this repository; inspired by ideas from community Herdr MCP experiments and the public Herdr docs, without reusing their source.