unifi-mcp

A lean, read-only MCP server that surfaces UniFi network data (a UCG-Fiber console) to Claude over stdio. Written against Ubiquiti's official API key (X-API-KEY); every tool is a GET, so it can only read — never change — your network.

Tools

get_isp_metrics defaults to period="5m", duration="24h"; use period="1h" with duration="7d"/"30d" for longer windows. The proxy tools default to the console's local site.

Related MCP server: UniFi MCP Server

Setup

Requires Python 3.11+ (the system 3.9 is too old for mcp). Uses uv.

cd unifi-mcp
uv venv --python 3.11
uv pip install mcp httpx

Configuration (environment)

• UNIFI_API_KEY (required) — your UniFi API key. Create it at unifi.ui.com → profile → API Keys, or locally under UniFi Network → Settings → Control Plane → Integrations.

  • The proxy tools (list_clients, clients_per_device, get_device_stats) require an Owner key. The cloud tools work with any key, including a read-only Viewer key.

• UNIFI_CONSOLE_ID (required for the proxy tools) — your console's id. Find it as the host id in the cloud GET /hosts response (or run list_hosts).

• UNIFI_SITE_ID (required for the proxy tools) — the local site id. Find it as data[0].id in the proxy GET /sites response (often the "Default" site).

None of these are hardcoded — all are read from the environment at runtime, and the API key is never logged, committed, or written to disk by this code. The cloud-only tools (list_hosts, list_sites, list_devices, get_isp_metrics) need just UNIFI_API_KEY.

Register with Claude Code

claude mcp add unifi --scope user \
  -e UNIFI_API_KEY="$UNIFI_API_KEY" \
  -e UNIFI_CONSOLE_ID="$UNIFI_CONSOLE_ID" \
  -e UNIFI_SITE_ID="$UNIFI_SITE_ID" \
  -- /ABS/PATH/unifi-mcp/.venv/bin/python -m unifi_mcp.server

Registering against the absolute venv interpreter (not uv run) keeps cold-start to a bare exec. --scope user keeps the registration (and the key) out of any project repo.

Skill: network health

skills/network-health/ is an optional Claude Code skill that turns the tools into a one-shot health summary — WAN/ISP status, offline devices, pending firmware updates, and client distribution per AP. Install it by copying the folder into your skills dir:

cp -r skills/network-health ~/.claude/skills/

Then ask Claude "how's my network?" and it orchestrates the relevant tools.

Tests

Two layers, both runnable without touching production state (everything is a read):

# Offline: projection/envelope logic pinned to real captured payloads (no key)
.venv/bin/python test_projections.py

# Live: exercises the tools against the real API; prints raw-keys -> kept so
# field-name mismatches are visible (needs UNIFI_API_KEY; proxy ops also need
# UNIFI_CONSOLE_ID and UNIFI_SITE_ID)
UNIFI_API_KEY=... UNIFI_CONSOLE_ID=... UNIFI_SITE_ID=... .venv/bin/python smoke_test.py

Design notes

• stdio transport — Claude launches the process on demand; zero idle cost.

• Read-only enforced in code — the HTTP client only ever issues GET (asserted), so the read-only guarantee holds even if Ubiquiti later ships write endpoints.

• Token-efficient — responses are projected down to monitoring-relevant fields (projections.py); ISP metrics are summarized per-WAN rather than returned raw.

• Two API envelopes — the cloud API uses cursor pagination (pageSize/nextToken); the connector proxy uses offset pagination (offset/limit) and some endpoints (e.g. statistics/latest) return a bare object with no envelope. client.py handles all three shapes.