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.8.1 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.3.0 calls the PiHerder bearer API. trigger_job accepts the same list as hosted /mcp on PiHerder v1.8.1, including container_start, container_stop, container_restart, and container_redeploy. MCP registry name: io.github.bjorngluck/piherder-mcp (see server.json). Herder notes: PiHerder v1.8.1. Adapter notes: v0.3.0 · CHANGELOG.md. PyPI still serves 0.2.0 until tag v0.3.0 is pushed.

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.

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.8.1: 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 16 tools. A missing scope hides that group. A token without read exits on stderr and lists nothing.

Read tools set readOnlyHint. set_features, trigger_job, 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: 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, nmap, and token admin are not tools. Adapter 0.2.0 did not send the four one-service jobs. This package does.

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 is still the package on PyPI. This commit is 0.3.0. Notes: docs/RELEASE_v0.3.0.md. The adapter badge reads the latest GitHub Release. The PyPI badge reads the latest package. The PiHerder badge is hand-typed v1.8.1 and links to tag v1.8.1.

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