PiHerder MCP

stdio process that lets Cursor, Claude, Codex, Windsurf, Continue, Goose, and other MCP clients 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. PiHerder v1.11.0 also serves POST /mcp on the herder, including browser sign-in. This adapter does not use that sign-in. It is the air-gapped fallback for a machine that cannot reach that URL. The public demo is not a target.

Adapter 0.4.4 calls the PiHerder bearer API. trigger_job accepts the same list as hosted /mcp on PiHerder v1.11.0, including container_start, container_stop, container_restart, and container_redeploy. start_move, read_discovery, and start_discovery match the hosted tools. list_discovery_devices, rename_discovery_device, set_discovery_device_state, link_discovery_device, unlink_discovery_device, purge_discovery_device, purge_stale_discovery_devices, and scan_discovery_device tidy LAN Discovery devices. The two purge calls send confirm=true on the request. list_servers and get_server include effective_backup_schedule, next_backup_run, and backup_scheduled. prune_docker starts a Docker prune of images, containers, both, or networks. Volume prune stays on the Docker page. list_alerts returns open notifications. prune_build_cache clears the Docker build cache and the buildx cache. replace_stale_mac ignores a stale LAN Discovery row and copies its custom fields. fleet_summary returns counts and states. since is optional ISO-8601 and does not replace summary. A herder without GET /api/v1/fleet/summary returns 404. MCP registry name: io.github.bjorngluck/piherder-mcp (see server.json). Herder notes: PiHerder v1.13.0. Adapter notes: v0.4.4 · CHANGELOG.md. PyPI package: 0.4.4.

Install

Full steps and scope notes: Agents (MCP).

export PIHERDER_URL='https://piherder.example.com'
export PIHERDER_TOKEN='ph_…'
uvx piherder-mcp

Requires uv (uvx). The package is on PyPI. uvx piherder-mcp installs the latest published release, 0.4.4. A machine that cached 0.4.3 needs uvx --refresh piherder-mcp, then a restart of the MCP client.

Git fallback (pin a branch or commit):

uvx --from git+https://github.com/bjorngluck/piherder-mcp.git piherder-mcp

Auth and tokens

1. In PiHerder 1.9.0: Settings → API management → Create new token → MCP agent. Details: API tokens.
2. read is required. jobs, edit, and files add the write tools. A token without read exits on stderr.
3. Set PIHERDER_URL and PIHERDER_TOKEN for the MCP process.

${PIHERDER_TOKEN} often does not expand inside client JSON env blocks. Many clients pass that string literally. Prefer one of:

• Export PIHERDER_TOKEN in the host environment and omit it from the client env object (if the client inherits the parent env), or
• Use the client's secret / env UI when it has one, or
• Paste the token once into the client config and keep that file out of git.

Samples in clients/ use a ph_… placeholder — replace it, or remove the key and rely on the host env. Do not commit real tokens.

Clients

Samples: clients/ (Cursor, Claude Desktop, Codex, Grok, Windsurf, Continue, Goose, Windows cmd /c). Path notes: clients/README.md.

Claude Desktop config locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Minimal Cursor / Claude-shaped entry:

{
  "mcpServers": {
    "piherder": {
      "command": "uvx",
      "args": ["piherder-mcp"],
      "env": {
        "PIHERDER_URL": "https://piherder.example.com",
        "PIHERDER_TOKEN": "ph_…"
      }
    }
  }
}

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

Tools

A token with read, jobs, edit, and files has these 32 tools. A missing scope hides that group. A token without read exits on stderr and lists nothing.

Read tools set readOnlyHint. set_features, prune_docker, prune_build_cache, replace_stale_mac, trigger_job, start_move, start_discovery, scan_discovery_device, rename_discovery_device, set_discovery_device_state, link_discovery_device, unlink_discovery_device, purge_discovery_device, purge_stale_discovery_devices, write_file, mkdir, rename_file, and delete_file set destructiveHint.

trigger_job types

server_id and job_type are required. source_filter, service, and os_steps are optional on the tool. For container_start, container_stop, container_restart, and container_redeploy, service (compose service name) and source_filter (compose project directory) are both required and are sent on POST /api/v1/servers/{id}/jobs. HTTP 202 means accepted. HTTP 409 means that job is already active: poll get_job and do not start another. The host feature flag and any feature:* scope still apply. The jobs scope is still required. Docker stays behind the server docker flag and feature:docker when the token is feature-restricted.

Not accepted on trigger_job: docker_stack_down, docker_stack_remove, template_drift_check, Move (service_migrate), undo (service_migrate_undo), and dest-up recover (service_migrate_dest_recover). SSH, the console, and token admin are not tools. A Move is start_move. A LAN Discovery scan is read_discovery and start_discovery. A device scan is scan_discovery_device. Adapter 0.3.1 did not send start_move, read_discovery, or start_discovery. Adapter 0.4.0 did not send the device tools. This package does.

Move

start_move takes server_id (the source), dest_server_id, project (the compose project name, not a directory), and confirm: true. It calls POST /api/v1/servers/{id}/moves. The source stack is left stopped. There is no undo. 409 means a stack, Move, or backup is already running. Poll get_job. That route is on PiHerder 1.10.0.

LAN Discovery

read_discovery lists saved ranges and the latest scan. Pass integration_id for recent scans, or integration_id and run_id for one scan.

start_discovery takes integration_id and confirm: true. Optional intensity is discovery, inventory, detailed, or deep. The body is confirm and intensity only. The scan uses the ranges saved on that integration. The agent does not choose the ranges. Vulnerability scripts stay off.

list_discovery_devices pages devices. state is new, known, linked, ignored, or stale. rename_discovery_device sets the operator name and leaves kind and map role alone. set_discovery_device_state sets known, new, or ignored. A linked device cannot be marked new. link_discovery_device and unlink_discovery_device tie a device to a fleet server. purge_discovery_device and purge_stale_discovery_devices need confirm: true and send confirm=true on the request. A linked device cannot be purged. Offline purge removes only stale rows. There is no undo. scan_discovery_device scans one device whose address sits inside the saved ranges. Default intensity is deep. Vulnerability scripts stay off.

These tools call /api/v1/discovery. A herder without that route returns 404. Device routes need PiHerder v1.11.0.

Wiki

Do not vendor this tree inside the PiHerder Docker image.

Publishing (maintainers)

piherder-mcp 0.1.1 was the first PyPI release. 0.4.4 is the current package. Prior package: 0.4.3. Notes: docs/RELEASE_v0.4.4.md. The adapter badge reads the latest GitHub Release. The PyPI badge reads the latest package. The PiHerder badge is hand-typed v1.13.0 and links to the v1.13.0 notes.

Trusted Publisher is already set: GitHub Environment pypi, workflow release.yml, owner bjorngluck, repository piherder-mcp. Later versions reuse it. github-release and publish-pypi still run independently after the build, so a green GitHub Release is not proof the package is on PyPI.

1. Package version is piherder_mcp.__version__. pyproject.toml reads it. CI checks server.json, the Continue sample, the changelog heading, and the README adapter line.
2. Write docs/RELEASE_vX.Y.Z.md on that commit. The release workflow uses it as the GitHub Release body. Tag and push: git tag -a vX.Y.Z <sha> -m "piherder-mcp X.Y.Z" && git push origin vX.Y.Z.
3. Confirm the Release has wheel and sdist assets and the publish-pypi job succeeded, then check pypi.org/project/piherder-mcp.
4. Optional: publish server.json to the MCP registry; keep the README <!-- mcp-name: … --> marker in sync with server.json name (the version test checks the marker).
5. Suggested GitHub topics: mcp, model-context-protocol, piherder, python, stdio, uvx.

See CHANGELOG.md. Workflow comments in .github/workflows/release.yml repeat the Trusted Publisher fields.

Tests

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

Tests mock HTTP. They do not call a live herder. CI runs Python 3.10–3.12.

Support

Optional. Nothing here is required to install the adapter.

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