unifi-mcp-server

# UniFi MCP Server

> **The MSP-style UniFi MCP — built around the official Site Manager API + Cloud Connector with cross-site analytics no other UniFi MCP exposes.**
>
> 54 tools split across 7 semantic-analysis aggregations, 9 raw Site Manager, and 35 Cloud Connector — plus 2 optional **local controller** tools that surface per-port error counters and SFP DDM the Cloud API doesn't expose. Severity verdicts (`healthy`/`info`/`warning`/`critical`) on top of curated thresholds. 8 MCP Prompts (4 fleet-wide ops + 4 MSP workflows). Read-only — Ubiquiti's API keys don't ship write yet.

[![npm](https://img.shields.io/npm/v/@us-all/unifi-mcp)](https://www.npmjs.com/package/@us-all/unifi-mcp)
[![downloads](https://img.shields.io/npm/dm/@us-all/unifi-mcp)](https://www.npmjs.com/package/@us-all/unifi-mcp)
[![tools](https://img.shields.io/badge/tools-54%2B2-blue)](#tools)
[![@us-all standard](https://img.shields.io/badge/built%20to-%40us--all%20MCP%20standard-blue)](https://github.com/us-all/mcp-toolkit/blob/main/STANDARD.md)
[![Glama MCP server](https://glama.ai/mcp/servers/us-all/unifi-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/us-all/unifi-mcp-server)

## Pre-flight diagnostic

```bash
npx -y @us-all/unifi-mcp --doctor
```

Validates env vars, pings Site Manager API, probes Cloud Connector (if owner key set), and checks category toggles before starting. Exits non-zero on critical issues so it works in CI / pre-deploy scripts.

## What it does that others don't

- **Site Manager analytics** — `site-health-timeline`, `summarize-site`, `firmware-inventory`, `compare-sites`, `wan-uptime-trend`, `top-clients-by-bandwidth`, `list-sites-overview`. No other UniFi MCP exposes these.
- **Severity verdicts**, not just numbers — every analysis tool returns `healthy / info / warning / critical / unknown` with a curated reason. Curated thresholds (e.g. WAN uptime <90% = `critical`, startupTime <1h = `critical` post-reboot).
- **Cloud Connector first-class** — 35 tools through the official `/v1/connector/consoles/{id}/...` proxy. `connectorAvailable` (capability) vs `connectorResolved` (this-call) split.
- **Aggregation tools** — fold 3–7 sequential calls into 1 with `caveats` array surfacing partial failures (e.g. Site Manager API can't window-bound WAN uptime — that's surfaced explicitly).
- **MCP Prompts** (8) — fleet ops: `triage-site-degradation`, `firmware-rollout-audit`, `wan-uptime-report`, `cross-site-anomaly-detection`. MSP workflows: `msp-onboard-site-checklist`, `msp-monthly-client-report`, `msp-fleet-firmware-plan`, `msp-bandwidth-complaint-investigation`.
- **Token-efficient by design** — smallest schema footprint of all `@us-all/*` MCPs (default ~5K tokens with owner key). Fleet of 200+ devices analyzable inside a single session.
- **Apps SDK card** — `summarize-site` renders as a fleet-status card on ChatGPT clients (online %, WAN uptime, gateway, devices) via `_meta["openai/outputTemplate"]`. Claude clients receive the same JSON content.
- **stdio + Streamable HTTP** — defaults to stdio. Set `MCP_TRANSPORT=http` for ChatGPT Apps SDK or remote clients (Bearer auth via `MCP_HTTP_TOKEN`).
- **Local controller direct access** (v1.13.0) — opt-in `UNIFI_LOCAL_*` env enables 2 tools that bypass the Cloud Connector and hit the controller's legacy `/api/s/{site}/stat/device/{mac}` directly on the LAN: `get-port-errors` (port-level rx/tx errors, link-flap counters, **SFP DDM** — Rx/Tx Power dBm, temperature, voltage, TX/RX fault) and `list-port-flap-summary` (fleet-wide port instability ranking). Surfaces data the Integration API doesn't expose. Requires LAN reachability.

## Try this — 5 prompts

Connect the server to Claude Desktop or Claude Code, then paste any of these:

1. **MSP morning check** — *"Fleet health check across all my UniFi sites. Flag anything not `healthy` with severity, top 3 issues."*
2. **Firmware rollout audit** — *"Find devices on outdated firmware across every site. Group by site, show current vs latest version, prioritize by criticality."*
3. **Site degradation triage** — *"USM site has WiFi complaints. Pull the last 24h: device statuses, WAN uptime, recent reboots, top-bandwidth clients. Anything anomalous?"*
4. **WAN SLA report** — *"Generate a monthly WAN uptime report for all sites. Surface outages > 5 minutes, dual-WAN failover events, sites below 99.5% target."*
5. **Cross-site anomaly** — *"Compare USS to my other sites — clients per AP, traffic patterns, device firmware mix. Flag outliers and suggest the most likely cause."*
6. **Port flap triage** *(requires `UNIFI_LOCAL_*`)* — *"Rank every port across all switches by instability score. For the top 3 worst offenders, pull SFP DDM if present and tell me whether the signal itself is bad or it's something downstream."*

## When to use this vs other UniFi MCPs

| | sirkirby/unifi-mcp | enuno/unifi-mcp-server | `@us-all/unifi-mcp` (this) |
|--|---|---|---|
| GitHub stars | 291 | 117 | — |
| Tool count | 224 | 74 | **54** |
| Scope | Network + Protect + Access + Drive | Network + multi-site + QoS + backup | Site Manager + Cloud Connector + analytics |
| Site Manager API | ❌ | partial | ✅ deep + analytics |
| Cloud Connector | ❌ | partial (3 modes) | ✅ avail/resolved split |
| UniFi Protect (cameras) | ✅ | ❌ | ❌ (out of scope) |
| UniFi Access (doors) | ✅ | ❌ | ❌ (out of scope) |
| Aggregation tools | ❌ | ❌ | ✅ 7 |
| Severity verdicts | ❌ | ❌ | ✅ curated thresholds |
| MCP Prompts | ❌ | ❌ | ✅ 8 (incl. 4 MSP workflows) |

Use **sirkirby** when you need cameras (Protect) or door access. Use **enuno** if you want raw Network API breadth. Use **this server** for MSP-style multi-site analytics, fleet triage, and any "is something off?" question across many consoles.

## Install

### Claude Desktop

```json
{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "@us-all/unifi-mcp"],
      "env": {
        "UNIFI_API_KEY": "<your-key>",
        "UNIFI_API_KEY_OWNER": "<owner-key-or-same-key-if-role=owner>"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add unifi -s user \
  -e UNIFI_API_KEY=<your-key> \
  -e UNIFI_API_KEY_OWNER=<owner-key> \
  -- npx -y @us-all/unifi-mcp
```

### Build from source

```bash
git clone https://github.com/us-all/unifi-mcp-server.git
cd unifi-mcp-server && pnpm install && pnpm build
node dist/index.js
```

## API keys — which one and where

The most common onboarding friction. UniFi has **two surfaces** through the same `https://api.ui.com/v1`:

| Surface | What it gives | Path | Env var |
|---|---|---|---|
| **Site Manager** | hosts, sites, devices summary, ISP metrics, SD-WAN configs (aggregated, console-wide) | `/v1/hosts`, `/v1/sites`, `/v1/devices`, `/v1/sd-wan-configs` | `UNIFI_API_KEY` |
| **Cloud Connector** | per-device, per-client, networks, firewall, WiFi (proxies to local controller) | `/v1/connector/consoles/{hostId}/...` | `UNIFI_API_KEY_OWNER` |

API key permissions inherit from the role of the account that created them.

| Account role | Site Manager | Cloud Connector |
|---|---|---|
| Admin (non-owner) | ✅ | ❌ 403 |
| **Owner** | ✅ | ✅ |

**If you have the owner role, set both env vars to the same key.** That's the most common case for `@us-all` operators.

Get the key: [unifi.ui.com](https://unifi.ui.com) → Settings → API → Generate. **View Only** is the only option in GA today (Full Access greyed out — Early Access program needed for write).

### Cloud Connector requirements

- Console firmware ≥ 5.0.3
- API path: `https://api.ui.com/v1/connector/consoles/{hostId}/{appPath}`
- Local `siteId` is a UUID, not the literal string `default`
- Available endpoints: Network integration API (`/network/integration/v1/sites`, devices, clients, networks). Legacy paths (`/api/s/{site}/stat/event`) return 404. Event logs / syslog not exposed.

### Local controller (optional, v1.13.0+)

Adds 2 tools that fill the gap left by Cloud Connector — per-port error counters, flap counters, and SFP DDM. These live in `/api/s/{site}/stat/device/{mac}` (legacy) and the official Network Integration API does not expose them (verified against OpenAPI spec v10.4.57).

Requirements:
- LAN/VPN reachability from the host running this MCP to the controller (typically `https://<controller-ip>`)
- A controller **local account** (Viewer / Limited Admin role is sufficient — Owner credentials NOT required)
- Self-signed cert handling: set `UNIFI_LOCAL_INSECURE=true` for stock UDM Pro

Auth flow: `POST /api/auth/login` (cookie) → all subsequent calls re-use the session, 401 triggers automatic re-login. Read-only.

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `UNIFI_API_KEY` | ✅ | — | API key from unifi.ui.com (any admin role) |
| `UNIFI_API_KEY_OWNER` | ❌ | — | Owner-role API key — enables 35 Cloud Connector tools. If your key has owner role, set this to the same value. |
| `UNIFI_API_URL` | ❌ | `https://api.ui.com/v1` | API base URL |
| `UNIFI_TOOLS` | ❌ | — | Comma-sep allowlist of categories. |
| `UNIFI_DISABLE` | ❌ | — | Comma-sep denylist. Ignored when `UNIFI_TOOLS` is set. |
| `MCP_TRANSPORT` | ❌ | `stdio` | `http` to enable Streamable HTTP transport |
| `MCP_HTTP_TOKEN` | conditional | — | Bearer token. Required when `MCP_TRANSPORT=http` |
| `MCP_HTTP_PORT` | ❌ | `3000` | HTTP listen port |
| `MCP_HTTP_HOST` | ❌ | `127.0.0.1` | HTTP bind host (DNS rebinding protection auto-enabled for localhost) |
| `MCP_HTTP_SKIP_AUTH` | ❌ | `false` | Skip Bearer auth — e.g. behind a reverse proxy that handles it |
| `UNIFI_LOCAL_URL` | ❌ | — | Local controller URL (e.g. `https://10.10.1.1`). Setting this + USER/PASS enables 2 `local` category tools. |
| `UNIFI_LOCAL_USER` | conditional | — | Controller local account username (required when `UNIFI_LOCAL_URL` set). Viewer/Limited-Admin role is sufficient. |
| `UNIFI_LOCAL_PASS` | conditional | — | Controller local account password (required when `UNIFI_LOCAL_URL` set). |
| `UNIFI_LOCAL_SITE` | ❌ | `default` | S