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.7.0 also serves POST /mcp on the herder. This adapter is the air-gapped fallback for a machine that cannot reach that URL. The public demo is not a target.

Adapter 0.2.0 calls the PiHerder 1.7.0 bearer API, including the wider trigger_job list. MCP registry name: io.github.bjorngluck/piherder-mcp (see server.json). Herder notes: PiHerder v1.7.0. The matching hosted tool list is the v1.8.0 train. Adapter notes: CHANGELOG.md.

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.2.0 is on PyPI after the v0.2.0 tag. Until then, pin the git commit.

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.7.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

trigger_job accepts backup, retention, os_patch, container_patch, os_update_check, container_update_check, host_reboot, docker_stack_check, docker_stack_deploy, docker_stack_stop, docker_stack_start, docker_stack_restart, template_deploy, and template_redeploy. For a docker_stack_* job, source_filter is the compose project path. A 409 is the job already running. Poll get_job. File bodies are capped at 256 KiB.

SSH, the console, Move, undo, nmap, and token admin are not tools. docker_stack_down, docker_stack_remove, and template_drift_check are not in this list.

Wiki

Do not vendor this tree inside the PiHerder Docker image.

Publishing (maintainers)

piherder-mcp 0.1.1 was the first PyPI release. 0.2.0 publishes when you push the v0.2.0 tag. The PyPI badge links to the project page. The Release badge links to that tag.

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. Tag the release commit and push the tag: 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