io.github.pete-builds/unifi

Official

by pete-builds · Python

UniFi Gateway

Safe-by-default UniFi MCP: Network + Protect + Access, multi-site, dry-run, audit log.

Manage UniFi network infrastructure with safe defaults, multi-site support, and audit logging.

Topics

dockerfastmcphomelabmcpmodel-context-protocolpythonubiquitiudmunifiucg-fiber

README.md11 KBView on GitHub

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.

bash

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

bash

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.

bash

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 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 distribution. Docker, .dxt one-click for Claude Desktop, Helm chart, uvx. Listed on the official MCP Registry. Container images are cosign-signed (keyless OIDC) with a CycloneDX SBOM attached to each release.
Network + Protect + Access. Network on by default; Protect and Access opt-in via MCP_UNIFI_MODULES_ENABLED=network,protect,access. Access ships read-only in v0.10 (door unlocks and credential issuance require session-token auth and are deferred). UniFi Drive is not in scope.

Quick start

Fastest cold-start: Docker + Claude Code in stub mode, no hardware required.

Start the container:

bash

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

bash

claude mcp add --transport http --scope user unifi http://localhost:3714/mcp

Verify the connection:
bash
```
claude mcp list
```
In a Claude Code session, ask: "list my UniFi devices". You'll get two stubbed devices back.

When you're ready to point at a real gateway, drop stub mode:

bash

docker run -d --rm -p 3714:3714 \
  -e STUB_MODE=false \
  -e UNIFI_HOST=192.168.1.1 \
  -e UNIFI_API_KEY=<your-local-api-key> \
  --name mcp-unifi ghcr.io/pete-builds/mcp-unifi:latest

Generate the API key under Settings → Control Plane → Integrations → Create API Key on the gateway.

Configuration

All config is read from environment variables (and .env when present). The five most common:

Variable	Default	Notes
`STUB_MODE`	`true`	When `false`, real-mode controller config is required.
`UNIFI_HOST`	(empty)	Gateway IP or hostname. Required in real mode.
`UNIFI_API_KEY`	(empty)	Local API key. Required in real mode.
`MCP_UNIFI_MODULES_ENABLED`	`network`	Set to `network,protect,access` to enable all three modules.
`MCP_UNIFI_CONTROLLERS_FILE`	(unset)	YAML file with named controllers for multi-site.

Full env var reference and the multi-site YAML schema are in the Configuration docs.

How this is built

The engineering scaffolding around the 86 tools, in case you want to know what's holding it up:

Test discipline. 619 tests covering unit, integration, and property-based (Hypothesis). HTTP is mocked with respx so tests don't hit a real controller. Coverage gated at 80% branch coverage in CI; current floor is 90%.

Code quality gates. Ruff (pycodestyle, pyflakes, isort, flake8-bugbear, pyupgrade, simplify, flake8-bandit security ruleset, comprehensions) plus mypy strict (no implicit Any, unreachable code flagged, unused ignores flagged). Pre-commit hooks run lint, format, types, and regenerate the tool manifest with a drift check, so bad code never reaches CI.

CI pipeline (5 gated jobs). Every PR runs lockfile-drift check → lint + type check → tests + coverage → multi-arch Docker build → Trivy filesystem and image scan (HIGH/CRITICAL fails the build). Each gates the next.

Release pipeline. A git tag vX.Y.Z push triggers a multi-arch (linux/amd64 + linux/arm64) Docker build, cosign keyless signing via sigstore OIDC, SLSA build provenance attestation, CycloneDX SBOM via Syft attached to the GitHub release, a .dxt bundle for Claude Desktop one-click install, GHCR push with vX.Y.Z / X.Y / latest tags, and an auto-bump of the example docker-compose.yml on main.

Dependency hygiene. Hash-pinned via pip install --require-hashes. A custom CI step verifies every pinned dep in requirements.in matches requirements.lock so no one can bump one without the other. Dependabot auto-merges safe patches. The base image is digest-pinned, not tag-pinned.

Container hardening. Runs as non-root UID 1000, no shell, no home directory. Read-only root filesystem enforced via Docker / Helm. /tmp is a 16MiB tmpfs. no-new-privileges set. All Linux capabilities dropped. Dedicated /health endpoint keeps the streamable-HTTP transport from logging 406 noise on every Docker healthcheck.

Security posture. Bearer-token authentication on the HTTP transport, secure by default (refuses to start without tokens). Audit log records each authenticated client_id per call with secret scrubbing on api_key, passphrase, password, secret, token substring matches. API keys wrapped in pydantic SecretStr. SECURITY.md with a private disclosure path.

Distribution surface. GHCR (signed multi-arch), Smithery (registered), MCP Registry (listed), Helm chart (Secret/Deployment/Service/Ingress/NetworkPolicy templates), .dxt bundle, uvx / pipx.

Documentation discipline. Astro Starlight site auto-deploys to GitHub Pages. The per-tool reference pages are generated from FastMCP introspection by scripts/generate_tool_manifest.py, and the pre-commit hook regenerates and drift-checks them so code and docs can't diverge. CHANGELOG follows Keep a Changelog format.

Version discipline. pyproject.toml, the git tag, the CHANGELOG entry, the Docker image tag, the docker-compose example, and the Helm chart appVersion all stay aligned because the release workflow enforces it. There is never a moment where the docs and the code disagree about what version this is.

Development

Clone, install dev dependencies, and wire up the pre-commit hooks:

bash

git clone https://github.com/pete-builds/mcp-unifi.git
cd mcp-unifi
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" pre-commit
pre-commit install

The pre-commit hooks run ruff (lint + format), mypy strict, and the tool manifest generator. The manifest hook regenerates docs/site/src/content/docs/tools/ whenever any file under src/mcp_unifi/modules/ changes and fails the commit if the on-disk manifest drifts from the registered tool surface. Run the tests with pytest.

To regenerate the manifest manually:

bash

python scripts/generate_tool_manifest.py        # write
python scripts/generate_tool_manifest.py --check  # CI-style drift check

Docs

License

MIT.

Install

Configuration

Environment variables

STUB_MODEdefault true

When true, the server returns realistic mock data and requires no UniFi hardware. Defaults to true so the image is functional out of the box.

UNIFI_HOST

IP address or hostname of the UniFi OS gateway (UCG-Fiber, UDM Pro, etc). Required when STUB_MODE=false and MCP_UNIFI_CONTROLLERS_FILE is unset.

UNIFI_API_KEYsecret

Local API key generated under Settings -> Control Plane -> Integrations on the gateway. Required when STUB_MODE=false and MCP_UNIFI_CONTROLLERS_FILE is unset.

UNIFI_SITEdefault default

UniFi controller site name. Defaults to 'default'.

UNIFI_VERIFY_SSLdefault false

Whether to verify the gateway's TLS certificate. Defaults to false because most home gateways use a self-signed cert.

MCP_UNIFI_CONTROLLERS_FILE

Path to a YAML file describing multiple named controllers for multi-site management. When set, the legacy UNIFI_HOST / UNIFI_API_KEY env vars are ignored. Each entry needs name, host, api_key, and optionally port, site, verify_ssl.

MCP_UNIFI_MODULES_ENABLEDdefault network

Comma-separated list of modules to load. Known values: 'network', 'protect', 'access'. Defaults to 'network'. Set to 'network,protect,access' to enable Protect and Access tools alongside Network. Access is read-only in v0.10.

UNIFI_ACCESS_HOST

UniFi Access hub IP or hostname. Required when the access module is enabled and STUB_MODE=false. Often the same host as UNIFI_HOST.

UNIFI_ACCESS_API_KEYsecret

UniFi Access API key. Separate from the Network API key; generated on the Access controller's developer settings. Required when the access module is enabled and STUB_MODE=false.

UNIFI_ACCESS_PORTdefault 12445

HTTPS port for the Access hub. Defaults to 12445 (the direct Access app port).

MCP_UNIFI_AUDIT_SINKdefault file

Audit log sink. One of 'file' (default), 'stdout', or 'syslog'. Every tool call is recorded to a JSONL stream with secrets scrubbed.

MCP_UNIFI_AUDIT_PATHdefault audit.jsonl

Path for the audit log file when MCP_UNIFI_AUDIT_SINK=file. Defaults to audit.jsonl in the process CWD.

claude_desktop_config.json

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pete-builds/mcp-unifi:0.15.3"
      ],
      "env": {
        "STUB_MODE": "true",
        "UNIFI_HOST": "<YOUR_UNIFI_HOST>",
        "UNIFI_API_KEY": "<YOUR_UNIFI_API_KEY>",
        "UNIFI_SITE": "default",
        "UNIFI_VERIFY_SSL": "false",
        "MCP_UNIFI_CONTROLLERS_FILE": "<YOUR_MCP_UNIFI_CONTROLLERS_FILE>",
        "MCP_UNIFI_MODULES_ENABLED": "network",
        "UNIFI_ACCESS_HOST": "<YOUR_UNIFI_ACCESS_HOST>",
        "UNIFI_ACCESS_API_KEY": "<YOUR_UNIFI_ACCESS_API_KEY>",
        "UNIFI_ACCESS_PORT": "12445",
        "MCP_UNIFI_AUDIT_SINK": "file",
        "MCP_UNIFI_AUDIT_PATH": "audit.jsonl"
      }
    }
  }
}