UniFi Gateway MCP server

mcp-unifi

<!-- mcp-name: io.github.pete-builds/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 dryrun=True and returns the predicted change set without writing. Composite tools (createiotnetwork, createguestnetwork, provisionhomelabservice, provisioncamera) 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: Network tools for devices, AP radio tuning, VLANs, WLANs, firewall, switch ports, port forwards, DHCP reservations, AP groups, observability, Threat Management / IDS-IPS, Honeypot, and Teleport VPN, plus opt-in Protect (cameras, motion events, smart detections, recording config) and Access (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). The full, always-current tool list is in the auto-generated Tool Manifest. 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 a UCG-Fiber on UniFi OS 5.1.33 running UniFi Network 10.6.101 (2026-09-13). Firewall reads cover both the legacy rulesets (listfirewallrules) and the Zone-Based Firewall (listfirewallpolicies, listfirewallzones), and auditopenports checks both, so a site that has migrated to zones is not reported as having no firewall. Firewall writes (createfirewallrule and friends) still target the legacy /rest/firewallrule API and do not create zone policies. 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.

HTTP transport refuses to start without a bearer token, so supply one:

export MCP_UNIFI_TOKEN=$(openssl rand -hex 32)
docker run --rm -p 3714:3714 \
  -e STUB_MODE=true \
  -e MCP_UNIFI_AUTH_TOKENS="$MCP_UNIFI_TOKEN" \
  ghcr.io/pete-builds/mcp-unifi:latest

Clients then send Authorization: Bearer $MCPUNIFITOKEN. For throwaway local testing on loopback only, -e MCPUNIFIAUTH_REQUIRED=false skips auth entirely; never use it on an interface reachable by anything else, because every connected client gets admin-equivalent access to the controller.

Claude Desktop (.dxt) — one-click

Download mcp-unifi-.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

Shortened. The full README is on GitHub.