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.

Pre-flight diagnostic

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

{
  "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

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

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 → 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 | Site slug for legacy /api/s/{site}/*. | | UNIFI_LOCAL_INSECURE | ❌ | false | Accept self-signed cert (typical for UDM Pro). |

Categories (9): analysis, raw, devices, clients, networks, firewall, wan, reference, local.

When MCP_TRANSPORT=http: POST /mcp (Bearer-auth JSON-RPC) + GET /health (public liveness).

Token efficiency

Smallest schema footprint of all @us-all/* MCPs.

| Scenario | Tools | Schema tokens | |----------|------:|--------------:| | default no-owner | 17 | 1,700 | | UNIFI_TOOLS=analysis | 8 | 1,000 (−42%) | | default with owner key | 52 | ~5,000 | | UNIFI_TOOLS=analysis + owner | 8 | 1,000 (−80%) |

Severity & thresholds

Every analysis tool returns one of:

• healthy — no issues
• info — informational, no action
• warning — needs attention
• critical — immediate action
• unknown — API failure or incomplete data

Curated thresholds:

| Condition | Severity | |---|---| | Device offline | critical | | startupTime < 1h | critical (just rebooted) | | startupTime < 24h | warning (recent reboot) | | startupTime < 72h | info (monitor) | | WAN uptime < 90% | critical | | WAN uptime < 95% | warning |

MCP Prompts (8)

Workflow templates available via MCP prompts/list. Four are fleet-ops; four are MSP-specific (managed-service-provider workflows).

Fleet ops:

• triage-site-degradation — site complaints workflow: device + WAN + reboots + clients in sequence.
• firmware-rollout-audit — fleet-wide firmware diff and rollout safety check.
• wan-uptime-report — monthly WAN SLA-style report across sites.
• cross-site-anomaly-detection — compare a site to fleet baseline; flag outliers.

MSP workflows:

• 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).
• msp-monthly-client-report — customer-facing monthly health report (one site → headline, network availability, devices, top users, recommendations) with non-technical phrasing.
• msp-fleet-firmware-plan — staggered N-wave rollout plan to a target firmware version, ordered by risk-tolerance with maintenance windows + rollback triggers.
• msp-bandwidth-complaint-investigation — triage 'internet is slow at site X' via WAN trend + ISP metrics + top clients + DPI categories + recent reboots.

MCP Resources

• unifi://site/{hostName}/devices — site's devices snapshot
• unifi://reboots/recent — recently rebooted devices fleet-wide

Tools (54 + 2 optional local)

9 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.

| Group | Tools | |-------|------:| | Semantic analysis (incl. aggregations) | 9 | | Site Manager raw | 9 | | Cloud Connector (devices/clients/networks/wifi/firewall/wan/reference) | 33 | | Sites local (list-local-sites, get-app-info) | 2 | | Local controller (get-port-errors, list-port-flap-summary) | 2 | | Meta (search-tools) | 1 |

Semantic analysis (9)

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)

Site Manager API (9)

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

Cloud Connector — devices (4)

get-device-details, get-device-by-id, get-device-statistics, list-pending-devices

Cloud Connector — clients (2)

list-site-clients, get-client-details

Cloud Connector — networks (3)

list-networks, get-network-details, get-network-references

Cloud Connector — WiFi (2)

list-wifi-broadcasts, get-wifi-broadcast-details

Cloud Connector — firewall / ACL / DNS (10)

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

Cloud Connector — traffic / WAN / VPN (5)

list-traffic-matching-lists, get-traffic-matching-list, list-wans, list-vpn-tunnels, list-vpn-servers

Cloud Connector — hotspot / reference (7)

list-vouchers, get-voucher-details, list-radius-profiles, list-device-tags, list-dpi-categories, list-dpi-applications, list-countries

Sites local (2)

list-local-sites, get-app-info

Local controller (2, opt-in via UNIFI_LOCAL_*)

• 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.
• 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).

Meta

search-tools — query other tools by keyword; always enabled.

Architecture

Claude → MCP stdio → src/index.ts
                      ├── tools/analysis.ts     → Site Manager API (UNIFI_API_KEY)
                      ├── tools/*.ts (raw)       → Site Manager API (UNIFI_API_KEY)
                      ├── tools/connector.ts     → Cloud Connector  (UNIFI_API_KEY_OWNER)
                      └── tools/local-ports.ts   → Local Controller (UNIFI_LOCAL_URL + LAN)
                      helpers/resolver.ts        → hostName ↔ ID mapping

Built on @us-all/mcp-toolkit:

• extractFields — token-efficient response projections
• aggregate(fetchers, caveats) — fan-out helper for summarize-site / site-health-timeline
• createWrapToolHandler — X-API-KEY redaction + ConnectorError/UniFiError extraction
• Retry: 3 attempts, exponential backoff (1s → 2s → 4s) + jitter, 30s Cloud Connector timeout

Limitations

• Read-only — UniFi API keys don't support write yet (Full Access role greyed out in GA).
• Rate limit — 10,000 req/min on stable v1; 100 req/min on Early Access.
• Cloud Connector partial proxy — Network integration API works; legacy paths return 404; event logs/syslog not exposed.
• ISP Metrics — may return 404 depending on account/plan.

Tech stack

Node.js 22+ • TypeScript strict ESM • pnpm • @modelcontextprotocol/sdk • zod v4 • dotenv.

License

MIT