mcp-unifi

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

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: 62 Network tools (devices, AP radio tuning, VLANs, WLANs, firewall, switch ports, port forwards, DHCP reservations, AP groups, observability, Threat Management / IDS-IPS, Honeypot, Teleport VPN), 11 Protect tools (cameras, motion events, smart detections, recording config), and 18 Access tools (doors, credentials, visitors, badge events, hubs / readers). 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). Works on any UniFi OS gateway running UniFi Network 9.x or newer (UDM, UDM Pro, UDM SE, UCG-Fiber, UCG-Ultra, UDR, UDW, UniFi OS Server), authenticated with a local API key from Settings → Control Plane → Integrations. Verified against UCG-Fiber fw 5.1.12.33296. 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, Protect, and Access together. The same process manages multiple UniFi sites in parallel

... View full README on GitHub