{
  "markdown": "# UniFi MCP Server\n\n> **The MSP-style UniFi MCP — built around the official Site Manager API + Cloud Connector with cross-site analytics no other UniFi MCP exposes.**\n>\n> 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.\n\n[![npm](https://img.shields.io/npm/v/@us-all/unifi-mcp)](https://www.npmjs.com/package/@us-all/unifi-mcp)\n[![downloads](https://img.shields.io/npm/dm/@us-all/unifi-mcp)](https://www.npmjs.com/package/@us-all/unifi-mcp)\n[![tools](https://img.shields.io/badge/tools-54%2B2-blue)](#tools)\n[![@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)\n[![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)\n\n## Pre-flight diagnostic\n\n```bash\nnpx -y @us-all/unifi-mcp --doctor\n```\n\nValidates 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.\n\n## What it does that others don't\n\n- **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.\n- **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).\n- **Cloud Connector first-class** — 35 tools through the official `/v1/connector/consoles/{id}/...` proxy. `connectorAvailable` (capability) vs `connectorResolved` (this-call) split.\n- **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).\n- **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`.\n- **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.\n- **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.\n- **stdio + Streamable HTTP** — defaults to stdio. Set `MCP_TRANSPORT=http` for ChatGPT Apps SDK or remote clients (Bearer auth via `MCP_HTTP_TOKEN`).\n- **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.\n\n## Try this — 5 prompts\n\nConnect the server to Claude Desktop or Claude Code, then paste any of these:\n\n1. **MSP morning check** — *\"Fleet health check across all my UniFi sites. Flag anything not `healthy` with severity, top 3 issues.\"*\n2. **Firmware rollout audit** — *\"Find devices on outdated firmware across every site. Group by site, show current vs latest version, prioritize by criticality.\"*\n3. **Site degradation triage** — *\"USM site has WiFi complaints. Pull the last 24h: device statuses, WAN uptime, recent reboots, top-bandwidth clients. Anything anomalous?\"*\n4. **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.\"*\n5. **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.\"*\n6. **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.\"*\n\n## When to use this vs other UniFi MCPs\n\n| | sirkirby/unifi-mcp | enuno/unifi-mcp-server | `@us-all/unifi-mcp` (this) |\n|--|---|---|---|\n| GitHub stars | 291 | 117 | — |\n| Tool count | 224 | 74 | **54** |\n| Scope | Network + Protect + Access + Drive | Network + multi-site + QoS + backup | Site Manager + Cloud Connector + analytics |\n| Site Manager API | ❌ | partial | ✅ deep + analytics |\n| Cloud Connector | ❌ | partial (3 modes) | ✅ avail/resolved split |\n| UniFi Protect (cameras) | ✅ | ❌ | ❌ (out of scope) |\n| UniFi Access (doors) | ✅ | ❌ | ❌ (out of scope) |\n| Aggregation tools | ❌ | ❌ | ✅ 7 |\n| Severity verdicts | ❌ | ❌ | ✅ curated thresholds |\n| MCP Prompts | ❌ | ❌ | ✅ 8 (incl. 4 MSP workflows) |\n\nUse **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.\n\n## Install\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@us-all/unifi-mcp\"],\n      \"env\": {\n        \"UNIFI_API_KEY\": \"<your-key>\",\n        \"UNIFI_API_KEY_OWNER\": \"<owner-key-or-same-key-if-role=owner>\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add unifi -s user \\\n  -e UNIFI_API_KEY=<your-key> \\\n  -e UNIFI_API_KEY_OWNER=<owner-key> \\\n  -- npx -y @us-all/unifi-mcp\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/us-all/unifi-mcp-server.git\ncd unifi-mcp-server && pnpm install && pnpm build\nnode dist/index.js\n```\n\n## API keys — which one and where\n\nThe most common onboarding friction. UniFi has **two surfaces** through the same `https://api.ui.com/v1`:\n\n| Surface | What it gives | Path | Env var |\n|---|---|---|---|\n| **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` |\n| **Cloud Connector** | per-device, per-client, networks, firewall, WiFi (proxies to local controller) | `/v1/connector/consoles/{hostId}/...` | `UNIFI_API_KEY_OWNER` |\n\nAPI key permissions inherit from the role of the account that created them.\n\n| Account role | Site Manager | Cloud Connector |\n|---|---|---|\n| Admin (non-owner) | ✅ | ❌ 403 |\n| **Owner** | ✅ | ✅ |\n\n**If you have the owner role, set both env vars to the same key.** That's the most common case for `@us-all` operators.\n\nGet 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).\n\n### Cloud Connector requirements\n\n- Console firmware ≥ 5.0.3\n- API path: `https://api.ui.com/v1/connector/consoles/{hostId}/{appPath}`\n- Local `siteId` is a UUID, not the literal string `default`\n- 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.\n\n### Local controller (optional, v1.13.0+)\n\nAdds 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).\n\nRequirements:\n- LAN/VPN reachability from the host running this MCP to the controller (typically `https://<controller-ip>`)\n- A controller **local account** (Viewer / Limited Admin role is sufficient — Owner credentials NOT required)\n- Self-signed cert handling: set `UNIFI_LOCAL_INSECURE=true` for stock UDM Pro\n\nAuth flow: `POST /api/auth/login` (cookie) → all subsequent calls re-use the session, 401 triggers automatic re-login. Read-only.\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `UNIFI_API_KEY` | ✅ | — | API key from unifi.ui.com (any admin role) |\n| `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. |\n| `UNIFI_API_URL` | ❌ | `https://api.ui.com/v1` | API base URL |\n| `UNIFI_TOOLS` | ❌ | — | Comma-sep allowlist of categories. |\n| `UNIFI_DISABLE` | ❌ | — | Comma-sep denylist. Ignored when `UNIFI_TOOLS` is set. |\n| `MCP_TRANSPORT` | ❌ | `stdio` | `http` to enable Streamable HTTP transport |\n| `MCP_HTTP_TOKEN` | conditional | — | Bearer token. Required when `MCP_TRANSPORT=http` |\n| `MCP_HTTP_PORT` | ❌ | `3000` | HTTP listen port |\n| `MCP_HTTP_HOST` | ❌ | `127.0.0.1` | HTTP bind host (DNS rebinding protection auto-enabled for localhost) |\n| `MCP_HTTP_SKIP_AUTH` | ❌ | `false` | Skip Bearer auth — e.g. behind a reverse proxy that handles it |\n| `UNIFI_LOCAL_URL` | ❌ | — | Local controller URL (e.g. `https://10.10.1.1`). Setting this + USER/PASS enables 2 `local` category tools. |\n| `UNIFI_LOCAL_USER` | conditional | — | Controller local account username (required when `UNIFI_LOCAL_URL` set). Viewer/Limited-Admin role is sufficient. |\n| `UNIFI_LOCAL_PASS` | conditional | — | Controller local account password (required when `UNIFI_LOCAL_URL` set). |\n| `UNIFI_LOCAL_SITE` | ❌ | `default` | Site slug for legacy `/api/s/{site}/*`. |\n| `UNIFI_LOCAL_INSECURE` | ❌ | `false` | Accept self-signed cert (typical for UDM Pro). |\n\n**Categories** (9): `analysis`, `raw`, `devices`, `clients`, `networks`, `firewall`, `wan`, `reference`, `local`.\n\nWhen `MCP_TRANSPORT=http`: `POST /mcp` (Bearer-auth JSON-RPC) + `GET /health` (public liveness).\n\n### Token efficiency\n\nSmallest schema footprint of all `@us-all/*` MCPs.\n\n| Scenario | Tools | Schema tokens |\n|----------|------:|--------------:|\n| default no-owner | 17 | 1,700 |\n| `UNIFI_TOOLS=analysis` | 8 | **1,000** (−42%) |\n| default with owner key | 52 | ~5,000 |\n| `UNIFI_TOOLS=analysis` + owner | 8 | **1,000** (−80%) |\n\n## Severity & thresholds\n\nEvery analysis tool returns one of:\n- `healthy` — no issues\n- `info` — informational, no action\n- `warning` — needs attention\n- `critical` — immediate action\n- `unknown` — API failure or incomplete data\n\nCurated thresholds:\n\n| Condition | Severity |\n|---|---|\n| Device offline | `critical` |\n| `startupTime < 1h` | `critical` (just rebooted) |\n| `startupTime < 24h` | `warning` (recent reboot) |\n| `startupTime < 72h` | `info` (monitor) |\n| WAN uptime < 90% | `critical` |\n| WAN uptime < 95% | `warning` |\n\n## MCP Prompts (8)\n\nWorkflow templates available via MCP `prompts/list`. Four are fleet-ops; four are MSP-specific (managed-service-provider workflows).\n\n**Fleet ops:**\n- `triage-site-degradation` — site complaints workflow: device + WAN + reboots + clients in sequence.\n- `firmware-rollout-audit` — fleet-wide firmware diff and rollout safety check.\n- `wan-uptime-report` — monthly WAN SLA-style report across sites.\n- `cross-site-anomaly-detection` — compare a site to fleet baseline; flag outliers.\n\n**MSP workflows:**\n- `msp-onboard-site-checklist` — pass/fail readiness checklist for a newly added customer site (firmware floor, console connectivity, uptime trend, connector availability, firewall sanity, recent reboots, pending devices).\n- `msp-monthly-client-report` — customer-facing monthly health report (one site → headline, network availability, devices, top users, recommendations) with non-technical phrasing.\n- `msp-fleet-firmware-plan` — staggered N-wave rollout plan to a target firmware version, ordered by risk-tolerance with maintenance windows + rollback triggers.\n- `msp-bandwidth-complaint-investigation` — triage 'internet is slow at site X' via WAN trend + ISP metrics + top clients + DPI categories + recent reboots.\n\n## MCP Resources\n\n- `unifi://site/{hostName}/devices` — site's devices snapshot\n- `unifi://reboots/recent` — recently rebooted devices fleet-wide\n\n## Tools (54 + 2 optional local)\n\n9 categories. Use `search-tools` to discover at runtime; full list collapsed below. Cloud Connector tools (33) only register when `UNIFI_API_KEY_OWNER` is set; without it the surface is 19 tools. Local controller tools (2) only register when `UNIFI_LOCAL_URL/USER/PASS` are set.\n\n| Group | Tools |\n|-------|------:|\n| Semantic analysis (incl. aggregations) | 9 |\n| Site Manager raw | 9 |\n| Cloud Connector (devices/clients/networks/wifi/firewall/wan/reference) | 33 |\n| Sites local (`list-local-sites`, `get-app-info`) | 2 |\n| **Local controller** (`get-port-errors`, `list-port-flap-summary`) | 2 |\n| Meta (`search-tools`) | 1 |\n\n<details>\n<summary>Full tool list</summary>\n\n### Semantic analysis (9)\n`list-sites-overview`, `analyze-site-health`, `detect-recent-reboots`, `compare-sites`, `firmware-inventory`, `wan-uptime-trend`, `top-clients-by-bandwidth`, `summarize-site` *(aggregation)*, `site-health-timeline` *(aggregation)*\n\n### Site Manager API (9)\n`list-hosts`, `get-host`, `list-sites`, `list-devices`, `get-isp-metrics` (optional), `query-isp-metrics` (optional), `list-sdwan-configs`, `get-sdwan-config`, `get-sdwan-config-status`\n\n### Cloud Connector — devices (4)\n`get-device-details`, `get-device-by-id`, `get-device-statistics`, `list-pending-devices`\n\n### Cloud Connector — clients (2)\n`list-site-clients`, `get-client-details`\n\n### Cloud Connector — networks (3)\n`list-networks`, `get-network-details`, `get-network-references`\n\n### Cloud Connector — WiFi (2)\n`list-wifi-broadcasts`, `get-wifi-broadcast-details`\n\n### Cloud Connector — firewall / ACL / DNS (10)\n`list-firewall-zones`, `get-firewall-zone`, `list-firewall-policies`, `get-firewall-policy`, `get-firewall-policy-ordering`, `list-acl-rules`, `get-acl-rule`, `get-acl-rule-ordering`, `list-dns-policies`, `get-dns-policy`\n\n### Cloud Connector — traffic / WAN / VPN (5)\n`list-traffic-matching-lists`, `get-traffic-matching-list`, `list-wans`, `list-vpn-tunnels`, `list-vpn-servers`\n\n### Cloud Connector — hotspot / reference (7)\n`list-vouchers`, `get-voucher-details`, `list-radius-profiles`, `list-device-tags`, `list-dpi-categories`, `list-dpi-applications`, `list-countries`\n\n### Sites local (2)\n`list-local-sites`, `get-app-info`\n\n### Local controller (2, opt-in via `UNIFI_LOCAL_*`)\n- `get-port-errors` — per-port `rx_errors` / `tx_errors` / `rx_dropped` / `tx_dropped` + link state, plus persistent flap counters (`linkDownCount`, `stpChangeCount`, `anomalies`) and **SFP DDM** when a transceiver is present (`rxPowerDbm`, `txPowerDbm`, `temperatureC`, `voltageV`, `txBiasMa`, `rxFault`, `txFault`, vendor/part/serial). `onlyProblems` filter for triage.\n- `list-port-flap-summary` — iterates all switches in the controller, ranks ports fleet-wide by score `linkDownCount*2 + stpChangeCount + rx_errors + tx_errors`. Surfaces the unstable cables / transceivers / NIC-power-save endpoints anywhere in the site at once. Counters are persistent across queries (reset only on switch reboot).\n\n### Meta\n`search-tools` — query other tools by keyword; always enabled.\n\n</details>\n\n## Architecture\n\n```\nClaude → MCP stdio → src/index.ts\n                      ├── tools/analysis.ts     → Site Manager API (UNIFI_API_KEY)\n                      ├── tools/*.ts (raw)       → Site Manager API (UNIFI_API_KEY)\n                      ├── tools/connector.ts     → Cloud Connector  (UNIFI_API_KEY_OWNER)\n                      └── tools/local-ports.ts   → Local Controller (UNIFI_LOCAL_URL + LAN)\n                      helpers/resolver.ts        → hostName ↔ ID mapping\n```\n\nBuilt on [`@us-all/mcp-toolkit`](https://github.com/us-all/mcp-toolkit):\n- `extractFields` — token-efficient response projections\n- `aggregate(fetchers, caveats)` — fan-out helper for `summarize-site` / `site-health-timeline`\n- `createWrapToolHandler` — `X-API-KEY` redaction + `ConnectorError`/`UniFiError` extraction\n- Retry: 3 attempts, exponential backoff (1s → 2s → 4s) + jitter, 30s Cloud Connector timeout\n\n## Limitations\n\n- **Read-only** — UniFi API keys don't support write yet (Full Access role greyed out in GA).\n- **Rate limit** — 10,000 req/min on stable v1; 100 req/min on Early Access.\n- **Cloud Connector partial proxy** — Network integration API works; legacy paths return 404; event logs/syslog not exposed.\n- **ISP Metrics** — may return 404 depending on account/plan.\n\n## Tech stack\n\nNode.js 22+ • TypeScript strict ESM • pnpm • `@modelcontextprotocol/sdk` • zod v4 • dotenv.\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 17104,
  "sha": "a5a8c3b83aa226c513ce2a36ab349bc667a7a4095cc2b16214f9209bd1aa9b4a",
  "repo_slug": "us-all/unifi-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_us_all_unifi_04f59504/readme"
}