io.github.us-all/unifi
UniFi semantic-analysis MCP β fleet health, anomaly detection, cross-site analytics
Ask AI about io.github.us-all/unifi
Powered by Claude Β· Grounded in docs
I know everything about io.github.us-all/unifi. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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. 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 / unknownwith a curated reason. Curated thresholds (e.g. WAN uptime <90% =critical, startupTime <1h =criticalpost-reboot). - Cloud Connector first-class β 35 tools through the official
/v1/connector/consoles/{id}/...proxy.connectorAvailable(capability) vsconnectorResolved(this-call) split. - Aggregation tools β fold 3β7 sequential calls into 1 with
caveatsarray 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-siterenders 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=httpfor ChatGPT Apps SDK or remote clients (Bearer auth viaMCP_HTTP_TOKEN).
Try this β 5 prompts
Connect the server to Claude Desktop or Claude Code, then paste any of these:
- MSP morning check β "Fleet health check across all my UniFi sites. Flag anything not
healthywith severity, top 3 issues." - Firmware rollout audit β "Find devices on outdated firmware across every site. Group by site, show current vs latest version, prioritize by criticality."
- Site degradation triage β "USM site has WiFi complaints. Pull the last 24h: device statuses, WAN uptime, recent reboots, top-bandwidth clients. Anything anomalous?"
- 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."
- 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."
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 | 51 |
| 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
siteIdis a UUID, not the literal stringdefault - 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.
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 |
Categories (8): analysis, raw, devices, clients, networks, firewall, wan, reference.
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 issuesinfoβ informational, no actionwarningβ needs attentioncriticalβ immediate actionunknownβ 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 snapshotunifi://reboots/recentβ recently rebooted devices fleet-wide
Tools (54)
8 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 21 tools.
| 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 |
Meta (search-tools) | 1 |
Full tool list
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
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)
helpers/resolver.ts β hostName β ID mapping
Built on @us-all/mcp-toolkit:
extractFieldsβ token-efficient response projectionsaggregate(fetchers, caveats)β fan-out helper forsummarize-site/site-health-timelinecreateWrapToolHandlerβX-API-KEYredaction +ConnectorError/UniFiErrorextraction- 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 18+ β’ TypeScript strict ESM β’ pnpm β’ @modelcontextprotocol/sdk β’ zod v4 β’ dotenv.
