Kuma

Proof of concept for a minimal Kuma MCP-compatible wrapper using the existing CSV-driven Kuma API builder.

Why

This project demonstrates a protocol-friendly interface on top of the Uptime Kuma API sync engine. It reuses the existing builder backend while exposing a PoC MCP-style command entrypoint.

Project Layout

• main.py
• main_mcp.py
• monitor.csv
• requirements.txt
• .env.example
• kuma_builder/config.py
• kuma_builder/inventory.py
• kuma_builder/kuma_client.py
• kuma_builder/sync.py
• kuma_builder/mcp_protocol.py

Setup

cd /home/sladmin/kuma_mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Edit .env:

KUMA_URL=http://127.0.0.1:3001
KUMA_USER=admin
KUMA_PASSWORD=CHANGE_ME

Usage

python main.py --csv monitor.csv
python main.py --csv monitor.csv --dry-run
python main.py --csv monitor.csv --prune
python main_mcp.py --csv monitor.csv --action syncInventory --output json
python main_mcp.py --csv monitor.csv --action previewSync --output json
python main_mcp.py --csv monitor.csv --action status --output json

Notes:

• Default behavior is non-destructive: create missing and update existing.
• --prune is a placeholder and currently does not delete anything.
• main_mcp.py is a PoC wrapper with a minimal JSON-style command interface.
• JSON output can be consumed by automation or a higher-level MCP wrapper.

Idempotency Rules

• Matches are based on normalized full path + name.
• Group rows create/reuse recursive parent groups.
• Existing monitors at the same full path are updated when configuration changes.
• Re-running should not create duplicates when entries are unchanged.

Acceptance Check

1. Run the script against monitor.csv.
2. Open Uptime Kuma and verify groups are nested under SoftLab Monitoring Root.
3. Re-run the script and verify there are no duplicates.