unifi-mcp

An MCP server for a UniFi network. It lets an LLM client diagnose the network (devices, clients, WAN, VPN, events), read metrics and traffic reports, summarise threats, audit the security posture, and make guarded changes to clients, devices, networks, WiFi and hotspot vouchers.

Important: the write tools change the live network. A bad network or WiFi change can cut clients off, and a restart can take the gateway down. Changes that could lock unifi-mcp itself out are previewed first and only run with confirm=true (see Protected networks). Give the server a key from a dedicated local admin (see Create the API key), and set UNIFI_MCP_READ_ONLY=true if you only want to look.

Tools

The guard column says what a change needs before it runs:

• none: runs straight away (reads, and changes that cannot lock anything out).

• confirm if protected: previews unless confirm=true when the target is on, or feeds, a protected network or is the gateway.

• always confirm: always previews first; runs only with confirm=true.

site is optional on every tool; with one site the tool uses it.

With a Site Manager key there are 39 tools (37 without). In read-only mode only the 19 read tools (17 without the key) are registered.

Firewall changes need Zone-Based Firewall, which has to be switched on in the UniFi UI (Settings → Policy Engine). The firewall write tools will come in a later release; unifi_list_firewall works today.

Related MCP server: UniFi MCP Server

Protected networks

UNIFI_MCP_PROTECTED_NETWORKS (default value pi-cluster; for example servers,management to set your own) names the networks unifi-mcp must not cut itself, or what runs on them, off from. A comma-separated list of names or ids; names ignore case. The guard works out the clients on those networks, the subnets, the devices and ports that carry them (including through daisy-chained switches and APs) and the gateway. A change that touches any of them previews first and runs only with confirm=true. A client or device the guard cannot place leans to confirm.

The names are looked up when the first change runs and again every five minutes, so a newly adopted device or a changed subnet is picked up without a restart. An unknown name is an error that lists the networks that exist, so a typo never leaves a network unprotected. An empty value is a startup error too; to protect only the gateway, say so with none. The protected list is logged at startup, as a warning when it is none. Renaming a protected network makes the guard refuse changes until UNIFI_MCP_PROTECTED_NETWORKS is updated to the new name (or use the network's id).

The guard works out the protected scope from the console's one (default) site, and every write tool is checked against that scope. Consoles with more than one site are not supported for changes yet: there the guard cannot pick a site, so changes fail with the list of sites. Use the read tools there, or UNIFI_MCP_READ_ONLY=true.

The machine running unifi-mcp is protected only if it sits on a protected network. A stdio run on a desktop on another network can block or disconnect that desktop without a confirm. Run read-only there, or add the desktop's network to UNIFI_MCP_PROTECTED_NETWORKS.

Write tools act only on an exact client or device: an id, MAC, IP or full name. A partial name comes back as candidates to ask again with, and nothing changes.

Configuration

The HTTP transport serves MCP at /mcp (bearer auth) and an unauthenticated /healthz for probes. Requests to the console time out after 15 seconds.

Get the fingerprint

echo | openssl s_client -connect 192.168.1.1:443 2>/dev/null | openssl x509 -noout -fingerprint -sha256

Pass the value after sha256 Fingerprint= as UNIFI_TLS_FINGERPRINT. UniFi OS regenerates its certificate on some upgrades; unifi-mcp then reports "console certificate changed: expected …, got …" and you update the fingerprint.

Create the API key

Create a dedicated local admin named unifi-mcp with the full administrator role (the Network API keys inherit their user's rights), sign in as it once, and create the key there. The menu depends on your Network version: Settings → Control Plane → Integrations, or Settings → Integrations. A dedicated admin means the audit log can tell unifi-mcp's changes from yours: unifi_audit_log takes actor: 'unifi-mcp'.

Run

docker run --rm -p 3000:3000 \
  -e UNIFI_URL=https://192.168.1.1 \
  -e UNIFI_API_KEY=your-api-key \
  -e UNIFI_TLS_FINGERPRINT=AA:BB:...:FF \
  -e UNIFI_MCP_TOKEN=a-long-random-secret \
  ghcr.io/jfms7s/unifi-mcp:v0.1.0

Pin a vX.Y.Z tag, not latest, so an upgrade is a decision you make.

Claude Code (~/.claude.json, mcpServers), over HTTP:

"unifi": {
  "type": "http",
  "url": "https://unifi-mcp.example.com/mcp",
  "headers": { "Authorization": "Bearer a-long-random-secret" }
}

From source

git clone https://github.com/jfms7s/unifi-mcp.git
cd unifi-mcp
npm ci
npm run build

Then point Claude Code at the build, over stdio:

"unifi": {
  "type": "stdio",
  "command": "node",
  "args": ["/path/to/unifi-mcp/dist/index.js"],
  "env": {
    "UNIFI_URL": "https://192.168.1.1",
    "UNIFI_API_KEY": "your-api-key",
    "UNIFI_TLS_FINGERPRINT": "AA:BB:...:FF",
    "UNIFI_MCP_READ_ONLY": "true"
  }
}

Development

npm ci
npm run typecheck
npm run lint
npm test
npm run build

Tests mock all HTTP with msw; no console is needed. npm run smoke calls every read tool once against a live console (set the variables above first) and prints each tool's name, OK or ERR and the size of its output, never the output. It is never run in CI.