mcp-unifi

Self-hosted UniFi MCP server. Multi-site config, dry-run previews, JSONL audit log. Network + Protect.

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: 46 Network tools (devices, VLANs, WLANs, firewall, switch ports, port forwards, observability) plus 12 opt-in Protect tools (cameras, motion events, smart detections, recording config). One container runs both modules, and one process manages multiple UniFi sites in parallel via a controller parameter. Works against a UCG-Fiber, UDM Pro, or any UniFi OS gateway using a local API key — no Site Manager or cloud account required.

Install in 30 seconds

Docker

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

docker run --rm -p 3714:3714 -e STUB_MODE=true \
  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

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 and Protect 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

46 Network tools plus 12 opt-in Protect tools. Network on by default; Protect via MCP_UNIFI_MODULES_ENABLED=network,protect.

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.13)  │
        │  ┌─────────────────────────────────────┐   │
        │  │  Tool dispatcher (per-module)       │   │
        │  ├──────────────────┬──────────────────┤   │
        │  │  Network module  │  Protect module  │   │
        │  │  (46 tools)      │  (12 tools, opt) │   │
        │  └─────┬────────────┴────────┬─────────┘   │
        │        │                     │             │
        │  ┌─────▼──────────┐  ┌───────▼──────────┐  │
        │  │  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   │
        └────────────────────────────────────────────┘

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.