mcp-unifi

mcp-unifi is a Model Context Protocol server for self-hosted UniFi gateways, built around the assumption that LLM-driven infrastructure calls need guardrails. Every destructive tool ships with a dry_run preview that returns the predicted change set without writing. Every call — preview or real — lands in a JSONL audit log with secrets scrubbed. Composite tools (e.g. “create an IoT VLAN with isolation rule”) capture pre-state and roll back applied steps if any sub-step fails.

Beyond the safety substrate: Network tools for devices, 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) modules. One container runs all three, and one process manages multiple UniFi sites in parallel via a controller parameter. The full, always-current tool list is in the 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) using a local API key. No Site Manager or cloud account required.

Install in 30 seconds

The HTTP transport refuses to start without a bearer token. All Docker / Helm examples below mint one and pass it through. For a full walkthrough, follow the linked install guide.

Docker

Long-running container for homelab and multi-client setups.

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

Docker install guide →

Claude Desktop (.dxt)

One-click install. Stdio transport, on-demand server.

Download mcp-unifi-<version>.dxt from the GitHub release page and double-click.

.dxt install guide →

Helm

Kubernetes deployment with multi-controller support.

helm repo add mcp-unifi \
  https://pete-builds.github.io/mcp-unifi/
helm install unifi mcp-unifi/mcp-unifi \
  --set auth.tokens=$(openssl rand -hex 32)

Helm install guide →

uvx / pipx

Quick one-off runs straight from GitHub.

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

uvx install guide →

Design

Safety primitives

dry_run=True on every destructive op returns the predicted change set without writing. Composites capture pre-state and roll back applied steps on partial failure. Every tool call lands in a JSONL audit log with secrets scrubbed.

Single image, multi-controller

One container runs Network, Protect, and Access together; one process manages multiple UniFi sites in parallel via the controller parameter and a YAML controllers file.

API-key-first auth

Uses the local API key from Settings → Control Plane → Integrations. No username/password storage, no cloud account, no Site Manager dependency.

Network + Protect + Access

Network on by default; opt in to Protect and Access via MCP_UNIFI_MODULES_ENABLED=network,protect,access. See the Tool Manifest for the current tool count per module.

Supply-chain hardened

Cosign-signed images, CycloneDX SBOM per release, GitHub-attested build provenance, hash-locked Python deps, non-root read-only container.

Architecture

┌─────────────────────────┐     ┌──────────────────────────┐
│  MCP client             │     │  YAML controllers file   │
│  (Claude Desktop /      │     │  (optional, multi-site)  │
│  Claude Code / Cursor)  │     └────────────┬─────────────┘
└────────────┬────────────┘                  │ loaded at boot
             │ stdio  /  Streamable HTTP     │
             ▼                               ▼
        ┌────────────────────────────────────────────────┐
        │  mcp-unifi server  (FastMCP, Python 3.14)      │
        │  ┌───────────────────────────────────────────┐ │
        │  │  Tool dispatcher (per-module)             │ │
        │  ├───────────────┬──────────────┬────────────┤ │
        │  │  Network      │  Protect     │  Access    │ │
        │  │  (default)    │  (opt-in)    │  (opt-in)  │ │
        │  └──────┬────────┴──────┬───────┴─────┬──────┘ │
        │         │               │             │        │
        │  ┌──────▼──────┐   ┌────▼─────────┐   │        │
        │  │ Safety layer│   │ Audit log    │   │        │
        │  │ dry_run +   │   │ JSONL,       │   │        │
        │  │ rollback    │   │ secrets      │   │        │
        │  │             │   │ scrubbed     │   │        │
        │  └──────┬──────┘   └──────────────┘   │        │
        └─────────┼────────────────────────────────┼─────┘
                  │ X-API-Key (local API)          │
                  ▼                                ▼
        ┌────────────────────────────────────────────────┐
        │  UniFi gateway  (UCG-Fiber / UDM / UniFi OS)   │
        │  /proxy/network/api  /proxy/protect/api        │
        │  UniFi Access hub  (:12445, separate API key)  │
        └────────────────────────────────────────────────┘

The dispatcher gates which modules are loaded at startup via MCP_UNIFI_MODULES_ENABLED; everything else (composite tools, audit log, rollback) is module-agnostic plumbing. The current per-module tool count is in the auto-generated Tool Manifest.