mcp-unifi

# 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.**

[![CI](https://github.com/pete-builds/mcp-unifi/actions/workflows/ci.yml/badge.svg)](https://github.com/pete-builds/mcp-unifi/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-91%25-brightgreen)](https://github.com/pete-builds/mcp-unifi)
[![cosign](https://img.shields.io/badge/cosign-signed-blue)](https://github.com/pete-builds/mcp-unifi/releases)
[![MCP](https://img.shields.io/badge/MCP-stdio%20%2B%20Streamable%20HTTP-brightgreen.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An [MCP server](https://modelcontextprotocol.io/) 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: **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](https://pete-builds.github.io/mcp-unifi/tools/). 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 (`list_firewall_rules`) and the Zone-Based Firewall (`list_firewall_policies`, `list_firewall_zones`), and `audit_open_ports` checks both, so a site that has migrated to zones is not reported as having no firewall. Firewall writes (`create_firewall_rule` 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:

```bash
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 $MCP_UNIFI_TOKEN`. For throwaway local
testing on loopback only, `-e MCP_UNIFI_AUTH_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-<version>.dxt` from the [latest release](https://github.com/pete-builds/mcp-unifi/releases) 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> \
  --set auth.tokens=$(openssl rand -hex 32)
```

The chart ships `auth.required: true` with `auth.tokens: ""`, so the pod will not
start until you set a token (or `--set auth.required=false`, which is only
appropriate for a trusted single-tenant cluster).

### 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](https://pete-builds.github.io/mcp-unifi/).

## Design

- **Read-only mode.** `MCP_UNIFI_READONLY=true` makes the server structurally unable to change anything: mutating tools are hidden from `tools/list` *and* refused on `tools/call`, so naming a hidden tool gets a normal error envelope instead of a write. Classification is declared per tool at registration (`@audited("list_networks", mutates=False)`), never inferred from tool names — twelve mutating tools, `confirm_destructive_action` among them, carry no `create_`/`update_`/`delete_`/`set_` prefix. Registration fails if a tool has not declared a classification, so a new tool cannot default into being callable. Defense in depth on top of a read-only UniFi API key, not a replacement for it.
- **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 (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.

1. Start the container. Auth is on by default, so mint a token first:

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

2. Register it with Claude Code, passing the token:

   ```bash
   claude mcp add --transport http --scope user unifi http://localhost:3714/mcp \
     --header "Authorization: Bearer $MCP_UNIFI_TOKEN"
   ```

3. Verify the connection:

   ```bash
   claude mcp list
   ```

4. In a Claude Code session, ask: *"list my UniFi devices"*. You'll get two stubbed devices back.

5. 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> \
     -e MCP_UNIFI_AUTH_TOKENS="$MCP_UNIFI_TOKEN" \
     --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 six 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_READONLY` | `false` | When `true`, mutating tools are hidden and refused. See the [Security guide](https://pete-builds.github.io/mcp-unifi/guides/security/#read-only-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. |
| `MCP_UNIFI_OTEL_ENABLED` | `false` | Optional OpenTelemetry tracing, one span per tool call. Off by default and the SDK is not a dependency. See [Operations](docs/operations.md). |
| `UNIFI_API_KEY_FILE` | (unset) | Read the API key from a file (a Docker or Kubernetes secret mount) instead of `UNIFI_API_KEY`. Wins if both are set, and turns TLS verification on by default. |
| `UNIFI_ACCESS_API_KEY_FILE` | (unset) | File-backed form of `UNIFI_ACCESS_API_KEY`. |
| `UNIFI_OS_PASSWORD_FILE` | (unset) | File-backed form of `UNIFI_OS_PASSWORD`. |
| `MCP_UNIFI_AUTH_TOKEN_FILE` | (unset) | File holding one bearer token (or the full `MCP_UNIFI_AUTH_TOKENS` grammar). Adds to whatever `MCP_UNIFI_AUTH_TOKENS` defines. |
| `MCP_UNIFI_CLIENT_ID` | (unset) | Client name for the bare token in `MCP_UNIFI_AUTH_TOKEN_FILE`. |
| `UNIFI_PINNED_CERT` | (unset) | Path to the console's own certificate (PEM) from `mcp-unifi-pin-cert`. When set, that certificate is the only one the server will accept from this controller. See below. |

Full env var reference and the multi-site YAML schema are in the [Configuration docs](https://pete-builds.github.io/mcp