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