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.

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

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:

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

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

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.

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:

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.

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