Monitoring

Uptime Kuma Operator

kuma-pp-cli

Inspect Uptime Kuma v2 monitors, heartbeats, and incident context; retry changes are explicitly gated.

Printed by @keithah (Keith)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install kuma

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-kuma --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-kuma skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-kuma. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

View source on GitHub →

kuma-pp-cli is a small operator CLI for Uptime Kuma v2. It uses Kuma's Socket.IO protocol rather than pretending the dashboard is a REST API.

This catalog package is intentionally separate from the native kumactl HTTP MCP service. The package currently contains the generated Go CLI and its Socket.IO client; it does not install or embed a Python kumactl dependency, and it does not provide an MCP transport.

Configuration

Set UPTIME_KUMA_URL, UPTIME_KUMA_USERNAME, and UPTIME_KUMA_PASSWORD (or pass --url, --username, and --password). Never commit credentials.

Commands

kuma-pp-cli health
kuma-pp-cli monitors [--query text] [--json]
kuma-pp-cli heartbeats [--hours 3] [--monitor-id N] [--json]
kuma-pp-cli incident-context --monitor id-or-name [--lookback-minutes 60] [--json]
kuma-pp-cli set-retries --monitor id-or-name --maxretries N       # dry-run
kuma-pp-cli set-retries --monitor id-or-name --maxretries N --yes
kuma-pp-cli agent-context [--pretty]
kuma-pp-cli version
kuma-pp-cli --version

UPTIME_KUMA_URL must be the server origin (for example https://kuma.example.com). A dashboard page URL is reduced to its origin automatically.

agent-context emits machine-readable JSON describing every command, flag, and auth variable, so agents can introspect the CLI without parsing --help.

Native HTTP MCP service

For MCP clients, deploy the separately published native kumactl service rather than this generated Go CLI:

kumactl-mcp --transport streamable-http --host 127.0.0.1 --port 40108 --path /mcp

The native service uses the same UPTIME_KUMA_URL, UPTIME_KUMA_USERNAME, and UPTIME_KUMA_PASSWORD environment variables. This package preserves those variables for kuma-pp-cli; it does not rename the CLI to kumactl or add a dependency on the native service.

All mutations are operator-gated and dry-run by default. The client sends complete monitor objects for editMonitor, because Kuma v2 treats edits as full replacement.

Development

go test ./...
go vet ./...
go build ./...