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, and the herder does not open an MCP port. The public demo is not a target.

Adapter 0.1.1 talks to the token API that shipped with PiHerder 1.6.0. The contract for this cut is the v1.7 train. MCP registry name: io.github.bjorngluck/piherder-mcp (see server.json).

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 (piherder-mcp 0.1.1).

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: Settings → API management (mint a token). Prefer an MCP preset when that lands on the token page. 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.

Related MCP server: Puppet Enterprise MCP Server

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

Wiki

Do not vendor this tree inside the PiHerder Docker image.

Publishing (maintainers)

piherder-mcp 0.1.1 is the first PyPI release. The PyPI badge links to that project page. The Release badge links to the v0.1.1 GitHub Release.

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