mcp-unifi

Safety-first MCP server for self-hosted UniFi. Dry-run previews, JSONL audit log, composite rollback. Network + Protect.

An MCP server built around the assumption that LLM-driven infrastructure calls need guardrails. Every destructive tool accepts dry_run=True and returns the predicted change set without writing. Composite tools (create_iot_network, create_guest_network, provision_homelab_service, provision_camera) capture pre-state and roll back applied steps on partial failure. Every call — dry-run or real — lands in a JSONL audit log with secrets scrubbed; the included mcp-unifi-replay CLI can re-issue a log against a fresh controller.

Beyond the safety substrate: 46 Network tools (devices, VLANs, WLANs, firewall, switch ports, port forwards, observability) and 12 Protect tools (cameras, motion events, smart detections, recording config). Every tool accepts a controller parameter so one server instance manages multiple UniFi sites. Speaks both stdio (Claude Desktop, uvx, .dxt) and Streamable HTTP (Docker, Helm). Talks to a UCG-Fiber, UDM Pro, or any UniFi OS gateway via the local API key. No Site Manager or cloud account required.

Install

Four supported paths. Pick the one that matches how you run Claude.

Docker

Long-running container, Streamable HTTP on port 3714. Best for homelab and multi-client setups.

docker run --rm -p 3714:3714 -e STUB_MODE=true \
  ghcr.io/pete-builds/mcp-unifi:latest

Claude Desktop (.dxt) — one-click

Download mcp-unifi-<version>.dxt from the latest release and double-click. Configuration is through a built-in UI in Claude Desktop. The bundle ships the Python runtime; no separate install needed. Uses stdio transport.

Helm

helm repo add mcp-unifi https://pete-builds.github.io/mcp-unifi/
helm install unifi mcp-unifi/mcp-unifi \
  --set unifi.host=192.168.1.1 \
  --set unifi.apiKey=<your-local-api-key>

uvx / pipx

Quick one-off runs straight from the GitHub repo. Stdio transport.

uvx --from git+https://github.com/pete-builds/mcp-unifi mcp-unifi

Pin a release with @v0.5.0-rc.2 (or any tag) appended to the URL.

Full guides for each install path live in the docs site.

Design

• Safety primitives. Every destructive tool accepts dry_run=True and returns the predicted change set without writing. Composite tools (create_iot_network, create_guest_network, provision_homelab_service, provision_camera) capture pre-state and roll back applied steps on partial failure. Every tool call lands in a JSONL audit log with secrets scrubbed; the included mcp-unifi-replay CLI can re-issue a log against a fresh controller.
• Single image, multi-controller. One container runs Network and Protect together. The same process manages multiple UniFi sites in parallel via the controller parameter and a YAML controllers file (MCP_UNIFI_CONTROLLERS_FILE). No need to run a separate process per controller.
• API-key-first auth. Uses the local API key from Settings → Control Plane → Integrations against the /proxy/network/api endpoint. No username/password storage, no cloud account, no Site Manager dependency.
• **Multi-channel distribut

... View full README on GitHub