UniFi MCP Server
Read-only access to Ubiquiti UniFi's Cloud Site Manager API across every site on one UI.com account — sites, hosts, devices, WAN/ISP health, and SD-WAN config/status — for AI assistants and the WYRE Conduit gateway.
Sites —
unifi_list_sites: enumerate all visible sites with metadata (name, timezone, gateway MAC), aggregate device/client counts and network performance, plus your permission level.Hosts —
unifi_list_hosts(all consoles/network servers with hardware ID, IP, ownership, timestamps) andunifi_get_host(full detail for one host by ID).Devices —
unifi_list_devices: devices grouped by host, with MAC, IP, model, firmware, adoption/uptime; filter by host IDs or last-processed time. PII-bearing, admin-gated by default.WAN / ISP health —
unifi_get_isp_metrics(all linked sites, 5-minute or 1-hour granularity, by duration or explicit time range) andunifi_query_isp_metrics(same metrics scoped to specific host/site pairs; a filtered POST read).SD-WAN —
unifi_list_sdwan_configs(id/name/type),unifi_get_sdwan_config(hub/spoke topology, networks, routed subnets), andunifi_get_sdwan_config_status(deployment status, WAN IPs, latency, errors). Topology tools are admin-gated by default.Pagination — most list tools accept
pageSizeandnextTokenfor paged retrieval.
What it deliberately cannot do: no client-level listings or details (only aggregate counts), no VLAN/network/DHCP config, no WLAN/SSID or firewall-rule operations — those live on the local per-controller API, which is out of scope. The mutating generic connector-proxy endpoint is excluded by design, and the connector's own code makes zero write calls.
Provides read-only integration with Ubiquiti UniFi's Cloud Site Manager API, enabling listing of sites, hosts, and managed devices, retrieving WAN/ISP health metrics, and viewing SD-WAN configurations and deployment status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@UniFi MCP Server check WAN health and device inventory for all my sites"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
UniFi MCP Server
MCP server for Ubiquiti UniFi's Cloud Site Manager API - sites, hosts, devices, WAN/ISP health metrics, and SD-WAN configuration/status, for AI assistants and the WYRE Conduit gateway.
Scope: Cloud Site Manager API only (deliberate)
UniFi exposes two distinct API surfaces:
Local per-controller API (Network Application API,
developer.ui.com/network/...) - lives on each customer's own console/controller, requires a separate API key per site with no central integration point, and covers per-site configuration in depth: clients, networks/VLANs/DHCP, WLANs/SSIDs, firewall rules, port forwarding, etc.Cloud Site Manager API (
developer.ui.com/site-manager/..., base URLhttps://api.ui.com) - a single UI.com account key that aggregates data across every site adopted to that account, but exposes a much narrower read surface: sites, hosts, device inventory, WAN/ISP metrics, and SD-WAN config/status only.
This connector targets the Cloud Site Manager API only, per an explicit upstream scope decision - the local per-controller API is deferred, not implemented as a fallback.
Consequence for tool coverage: the Cloud Site Manager API does not expose several things a "typical" network-management connector would have - there is no client-listing/client-detail endpoint (only aggregate client counts inside a site's statistics), no VLAN/network/DHCP-config endpoint, no WLAN/SSID endpoint, and no firewall-rule endpoint as first-class operations. Those all live on the local per-controller API. This connector implements 9 of the 10 paths the Cloud Site Manager API's own published OpenAPI spec defines as dedicated, purpose-built read operations - see Tools below. The 10th path is the connector-proxy endpoint, covered in its own subsection below - it is excluded by design, not missed.
Related MCP server: UniFi MCP Server
Authentication
UniFi Site Manager authenticates with a single static X-API-Key header tied to a UI.com account - there is no OAuth flow, no token exchange, and no per-request expiry. Generate a key at unifi.ui.com under Settings > API Keys.
Two separate claims here, at deliberately different confidence levels - don't collapse them into one "read-only" statement:
Structurally verified (checked directly, stated with full confidence): this connector's own code makes zero mutating calls. Every function in
client.tscalls one of the 9 dedicated read operations below; noPOST/PUT/PATCH/DELETEcall exists anywhere insrc/, and the connector-proxy path (below) is never referenced under any name.Vendor-documented, not independently verified (hedged deliberately): Ubiquiti's own Getting Started documentation describes Site Manager API keys generally as read-only ("currently read-only... cannot be used to make modifications to your UniFi infrastructure"). Whether that's actually enforced server-side against the connector-proxy path specifically - i.e. whether UI.com's backend rejects a write verb sent through
/v1/connector/consoles/{id}/*path, versus the restriction being a documented policy rather than a hard technical block - has not been tested by WYRE. Nobody on this review sent a write verb against a live key to find out, correctly: that would be a destructive test against real customer infrastructure, not something to run without consent. Do not read this connector, or this README, as having established that the underlying API key cannot perform writes - only that this connector's own code never attempts one.
In gateway mode the key arrives per-request via the X-UniFi-Api-Key header; in local/stdio mode it's read once from UNIFI_API_KEY. HTTP mode also requires a signed X-Gateway-S2S header — see Configuration.
The connector-proxy endpoint (excluded by design)
The live spec (https://developer.ui.com/site-manager/v1.0.0/openapi.json - fetched directly with a plain curl/HTTP GET; this specific raw-JSON endpoint returns cleanly even though the interactive docs pages at developer.ui.com are a JS SPA that doesn't render via plain fetch) defines a 10th path beyond the 9 this connector implements: /v1/connector/consoles/{id}/*path, with all five HTTP methods - GET/POST/PUT/PATCH/DELETE (operationIds ConnectorGet/ConnectorPost/ConnectorPut/ConnectorPatch/ConnectorDelete). It is a generic reverse-proxy: api.ui.com forwards the request verbatim to the target console's local API at http://127.0.0.1/proxy/[path], reaching the console's full local Network/Protect/InnerSpace surface - the same local per-controller API this connector's Scope section defers, just reached through the cloud endpoint instead of the console directly. The spec documents it as genuinely mutating - its own example for DELETE removes hotspot vouchers - and available to a standard (non-organization) API key, scoped to consoles that key's owner controls; it is not gated behind an org-tier key. (WYRE has not sent a live write call against this path - see the hedge in Authentication above.)
This connector deliberately excludes the connector-proxy endpoint entirely, for the same reason the local per-controller API is out of scope: implementing it would mean re-exposing the whole local surface (clients, VLANs, WLANs, firewall rules, and genuine mutations) through one wildcard passthrough tool, defeating the purpose of scoping this connector to purpose-built cloud reads. No tool in this connector calls it, under any name.
Configuration
Copy .env.example and set the variables below.
Env var | Required | Description |
| For stdio and | UniFi Cloud Site Manager API key ( |
| No |
|
| No |
|
| Yes for HTTP | Service-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder ( |
| No | Set to exactly |
| No | Bind address when a real |
| No | HTTP port. Defaults to |
| No |
|
/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before the UniFi API key is read.
TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
-H "X-UniFi-Api-Key: $UNIFI_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'In AUTH_MODE=gateway, /mcp also requires X-UniFi-Api-Key. That header is the only credential source for that request. AUTH_MODE=env still requires the signed X-Gateway-S2S header, then uses UNIFI_API_KEY from the environment.
Tools
9 read-only tools, one per dedicated read operation in the Cloud Site Manager API's published spec (10 paths total on the live spec; the 10th, a generic mutating connector-proxy endpoint, is excluded by design - see Authentication above).
Sites
unifi_list_sites- list every site visible to this API key's account, with metadata (name, timezone, gateway MAC) and aggregate statistics (device/client counts, network performance).
Hosts
unifi_list_hosts- list every host (console / network-server application) associated with this API key's account.unifi_get_host- get detailed information about a single host by ID.
Devices
unifi_list_devices- list UniFi devices managed by hosts this account owns or super-admins, grouped by host. PII-bearing (MAC address, IP address, user-defined hostname/note per device) - admin-gated by default.
WAN / ISP Health
unifi_get_isp_metrics- WAN/ISP health and traffic metrics for every linked site, at 5-minute or 1-hour granularity.unifi_query_isp_metrics- the same metrics, scoped to specific host/site pairs and time ranges. APOSTon UniFi's API, but a filtered read, not a mutation.
SD-WAN
unifi_list_sdwan_configs- list every SD-WAN configuration (id/name/type only).unifi_get_sdwan_config- full topology for one SD-WAN configuration: hub/spoke sites, attached networks, and routed subnets (CIDR). Network-topology data - admin-gated by default.unifi_get_sdwan_config_status- deployment status for one SD-WAN configuration, including per-hub/spoke WAN IPs and latency. Network-topology data - admin-gated by default.
unifi_list_sites, unifi_list_hosts, unifi_get_host, unifi_get_isp_metrics, unifi_query_isp_metrics, and unifi_list_sdwan_configs are plain-read tier: sites/hosts are the navigational directory most other tools need site/host IDs from, and WAN metrics are aggregate performance data, not PII or topology.
Sensitivity
This connector's own 9 tools surface two categories of sensitive data even though every one of them is read-only: PII (device MAC addresses, IP addresses, user-defined hostnames on every device returned by unifi_list_devices) and network topology (SD-WAN hub/spoke routes and subnets in unifi_get_sdwan_config/unifi_get_sdwan_config_status). Those three tools default to isAdmin: true in the Conduit wiring; everything else is plain read. This is separate from, and does not account for, the connector-proxy endpoint described under Authentication - that endpoint isn't implemented here at all, so it isn't part of this connector's tier model.
Development
npm install
npm run build
npm test
npm run lint # tsc --noEmitDocker
The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a real S2S secret. In gateway mode, the UniFi API key arrives on each request as X-UniFi-Api-Key; it is not read from the environment.
docker build -t unifi-mcp .
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-p 127.0.0.1:8080:8080 \
unifi-mcpCompose refuses to start when CONDUIT_S2S_SECRET is unset. The gateway service sets AUTH_MODE=gateway, does not inject UNIFI_API_KEY, and publishes 127.0.0.1:8080:8080:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose upSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses UNIFI_API_KEY. It is separate from the gateway Compose service above.
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-e AUTH_MODE=env \
-e UNIFI_API_KEY=your-value \
-p 127.0.0.1:8080:8080 \
unifi-mcpLocal HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning. A non-loopback MCP_HTTP_HOST (including 0.0.0.0) is overridden:
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:httpLicense
Apache-2.0
Available Tools
9 toolsunifi_get_hostA
Get detailed information about a single host by ID (as returned by unifi_list_hosts).
Inputs: id (required).
unifi_get_isp_metricsA
Get WAN/ISP health and traffic metrics for every site linked to this API key's account, at 5-minute or 1-hour granularity. 5-minute data is retained at least 24h; 1-hour data at least 30 days. Provide either duration alone, or beginTimestamp/endTimestamp (not both).
Inputs: type (required), duration, endTimestamp, beginTimestamp.
unifi_get_sdwan_configA
Get the full topology for one SD-WAN configuration: variant, advanced settings, and every hub/spoke including their site/host IDs, attached network IDs, and routed subnets (CIDR). Network-topology data - admin-gated.
Inputs: id (required).
unifi_get_sdwan_config_statusA
Get deployment status for one SD-WAN configuration: generation/apply status, and per-hub/spoke details including WAN IPs, latency, routes, and any errors or warnings. Network-topology data - admin-gated.
Inputs: id (required).
unifi_list_devicesA
List UniFi devices managed by hosts this API key's account owns or super-admins, grouped by host. Each device includes its MAC address, IP address, model, firmware status, and adoption/uptime info. PII-bearing (device MAC/hostname/IP) - admin-gated.
Inputs: time, hostIds, pageSize, nextToken.
unifi_list_hostsA
List every host (UniFi console or network-server application) associated with this API key's UI.com account. Includes hardware ID, current IP address, ownership/block status, and registration/backup timestamps.
Inputs: pageSize, nextToken.
unifi_list_sdwan_configsA
List every SD-WAN configuration associated with this API key's account (id, name, type only).
Inputs: no named parameters.
unifi_list_sitesA
List every UniFi site (from hosts running the UniFi Network application) visible to this API key's UI.com account. Each entry includes the site and host IDs, site metadata (name, timezone, gateway MAC), aggregate statistics (device/client counts, network performance), and the caller's permission level on that site.
Inputs: pageSize, nextToken.
unifi_query_isp_metricsA
Get WAN/ISP health and traffic metrics for specific host/site pairs and time ranges. A filtered read, not a mutation, despite being a POST on UniFi's API. If the API key lacks access to a requested site, the response reports status:partialSuccess for a mixed result or fails outright if none are accessible.
Inputs: type (required), sites (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools are clearly distinct by resource type (sites, hosts, devices, SD-WAN configs, ISP metrics). The only potential confusion is between unifi_get_isp_metrics and unifi_query_isp_metrics, which both fetch WAN/ISP metrics—though one is account-wide and the other is a filtered query, the overlap could cause misselection.
All tools follow a consistent unifi_<verb>_<noun> snake_case pattern, with list for plural collections and get for singular resources. The minor deviation is query_isp_metrics using 'query' instead of 'get' for a similar read operation, slightly breaking the otherwise predictable pattern.
Nine tools is a well-scoped count for a UniFi network-management server. Each tool covers a distinct resource area (sites, hosts, devices, SD-WAN, ISP metrics) without unnecessary bloat or overlap.
The tool surface provides solid read-only coverage for the core UniFi resources, including listing and detail retrieval for hosts and SD-WAN configs, plus metrics for ISP health. Minor gaps exist—no singular site or device detail endpoints and no client-level information—but agents can work around these using the existing list operations.
Maintenance
Related MCP Connectors
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Unified API to query AWS, GCP, Azure and generate Terraform/CLI execution kits for AI agents.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to interact with Ubiquiti UniFi network infrastructure for monitoring devices, managing clients, and performing configuration tasks like blocking/unblocking devices and viewing network health.101GPL 3.0
- AlicenseDqualityDmaintenanceEnables comprehensive management of UniFi network infrastructure through the UniFi Cloud API, including device control, client management, camera settings, and access door control through natural language.39MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to manage and monitor UniFi Network Controllers through natural language. Provides 25 read-only tools for discovering devices and clients, viewing security configurations, analyzing network statistics, and exporting configuration data.41MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to manage UniFi network infrastructure through 50+ tools covering devices, clients, networks, WiFi, firewall rules, and guest access using the official UniFi Network API.525MIT