PiHerder MCP

stdio process that lets Cursor, Grok Build, Claude, and Codex call a PiHerder instance through the existing bearer API.

It runs on the computer that runs the agent. It is not part of the PiHerder image, and the herder does not open an MCP port. The public demo is not a target.

Adapter 0.1.0 (GitHub Release v0.1.0). It talks to the token API that shipped with PiHerder 1.6.0. The contract for this cut is the v1.7 train.

Install

Full steps, client samples, and what each scope can do: Agents (MCP).

The public docs site (piherder-docs.hacknow.info) is built from PiHerder main. That site’s Agents page is published when v1.7 merges. Until then, use the wiki file on v1.7.0-dev linked above.

The package is not on PyPI yet. Launch it from git:

export PIHERDER_URL='https://piherder.example.com'
export PIHERDER_TOKEN='ph_…'
uvx --from git+https://github.com/bjorngluck/piherder-mcp.git piherder-mcp

After a PyPI release the same program is uvx piherder-mcp.

1. In PiHerder: Settings → API management. Token page: API tokens.

2. read is required. jobs, edit, and files add the write tools. A token without read exits on stderr.

3. Put PIHERDER_URL and PIHERDER_TOKEN in the client config. Samples are in clients/. Do not commit the token.

Related MCP server: Puppet Enterprise MCP Server

Tools

trigger_job accepts backup, retention, os_patch, container_patch, os_update_check, and container_update_check. A 409 is the job already running. Poll get_job. File bodies are capped at 256 KiB.

SSH, the console, Move, undo, compose stack actions, and token admin are not tools.

Clients

Samples live in clients/. They use ${PIHERDER_TOKEN} so the secret stays out of git. Grok Build also loads a Cursor .cursor/mcp.json when Cursor MCP import is on. Codex needs clients/codex/config.toml.

The same operating note is in skills/piherder/SKILL.md (Grok), clients/cursor/piherder.mdc (Cursor), CLAUDE.md, and AGENTS.md.

Wiki

Do not vendor this tree inside the PiHerder Docker image.

Tests

pip install -e ".[dev]"
pytest -q

Tests mock HTTP. They do not call a live herder.

Support

Optional. Nothing here is required to install the adapter.

 

github.com/sponsors/bjorngluck · buymeacoffee.com/bjorngluck · Support the project