UniFi管理协议服务器

UniFi MCP

An MCP server that lets Claude interact with your UniFi infrastructure. Covers four UniFi APIs with 146 tools:

• Site Manager API (cloud) — hosts, sites, devices, ISP metrics, SD-WAN.
• Mobility API (cloud) — UMR mobile routers: workspaces, admins, devices, clients, and device name/network/WiFi updates.
• Network API — devices, clients, networks, WiFi, firewall, ACL rules, DNS, switching, traffic-matching lists, vouchers, and more.
• Protect API — cameras (incl. PTZ, RTSPS, snapshots, talkback), lights, sensors, sirens, speakers, fobs, relays, bridges, link stations, alarm hubs, arm profiles, events, users.

The Network and Protect APIs can be reached either through the cloud connector (a single unifi.ui.com key proxied through api.ui.com — no LAN access needed) or by connecting directly to a local console. See Reaching a console.

Features

Site Manager API (cloud)

Read-only access to your UniFi account via https://api.ui.com:

Mobility API (cloud)

UniFi Mobile Router (UMR) management via https://api.ui.com/v1/mobility (requires the mobility scope on your key):

Network API

Full CRUD access to a UniFi console (UDM, UCG, etc.), via the cloud connector or a local connection:

Protect API

Access to UniFi Protect devices, via the cloud connector or a local connection:

Prerequisites

• UniFi API key — generate at unifi.ui.com → API. Enable the Site Manager and UniFi Applications (Network, Protect) scopes; add mobility if you use UMR routers. The same key drives every API.

Reaching a console

Site Manager and Mobility are always available (they are cloud APIs). The Network and Protect tools need to reach a specific console, in one of two ways:

• Cloud connector (recommended). Set UNIFI_CONSOLE_ID to the console (host) ID. Requests are proxied through api.ui.com with your unifi.ui.com key — nothing needs LAN access. Find the ID via the list_hosts tool (the id field, e.g. 900A6F…:123456789).
• Local console. Set UNIFI_NETWORK_HOST / UNIFI_PROTECT_HOST to the console IP/hostname to connect directly over the LAN (self-signed certs, verification off by default).

If neither is configured for an application, its tools are simply not registered.

Quick start

Docker Compose (recommended — remote HTTP endpoint)

Runs the server as a streamable-HTTP service reachable from other machines:

cp .env.example .env          # set UNIFI_API_KEY and UNIFI_CONSOLE_ID
docker compose up -d --build
# MCP endpoint: http://<this-host>:8000/mcp

Put a TLS-terminating reverse proxy in front before exposing it publicly.

Docker (one-off / stdio)

docker build -t unifi-mcp .

# Cloud connector: one key drives all four APIs
docker run --rm -i \
  -e UNIFI_API_KEY=your-key \
  -e UNIFI_CONSOLE_ID=900A6F...:123456789 \
  unifi-mcp

Local (with uv)

uv sync
# stdio (default)
UNIFI_API_KEY=your-key UNIFI_CONSOLE_ID=... uv run unifi-mcp
# remote HTTP
UNIFI_API_KEY=your-key uv run unifi-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Configuration

When both a local host and a console ID are set for an application, local mode wins. By default UNIFI_API_KEY is used everywhere; set a per-API key only if a console needs a different one.

Multi-user web GUI (self-service SaaS mode)

The default docker compose up runs a hosted, multi-user service — no configuration required. Users self-register with a passkey and manage their own MCP connections through a web page; each connection maps one UniFi API key to the shared, OAuth-protected /mcp endpoint for Claude.

docker compose up -d --build
# open http://<host>:8000/  → register a passkey → add a connection

Behind HTTPS in production (passkeys require it), point a reverse proxy at the container and optionally set UNIFI_PUBLIC_URL.

Endpoints served on one port:

Accounts: passwordless, WebAuthn passkeys only — no default account. Anyone can self-register (optionally gate with UNIFI_ONBOARD_CODE). Each user owns as many connections as they want and can revoke any of them at any time (revoking also invalidates that connection's OAuth tokens).

Per-connection auth: each connection is a confidential OAuth client. Claude runs the authorization-code + PKCE flow with the issued id/secret and receives an access token bound to that connection; tool calls resolve its UniFi credentials from the token.

Consoles: onboarding loads the account's consoles (via list_hosts) so you can pick a default. A single connection can reach every console the account owns — each network_* / protect_* tool takes an optional console_id (discover IDs with list_hosts); omit it to use the default.

Zero-config by default:

• The Fernet encryption key is auto-generated and persisted to the data volume (secret.key) on first run — set UNIFI_SECRET_KEY only to supply your own.
• The public base URL (OAuth issuer, passkey origin, MCP URL shown to users) is auto-detected from each request (honoring X-Forwarded-Proto/Host). Set UNIFI_PUBLIC_URL to pin it.

Data at rest (JSON on the unifi-data volume):

• UniFi API keys and OAuth client secrets are encrypted (Fernet).
• OAuth access/refresh tokens and authorization codes are stored hashed (SHA-256) — raw bearer secrets are never written to disk.
• Passkey public keys, ownership, and console IDs are non-secret metadata.

Security notes:

• Passkeys require HTTPS (except localhost) — terminate TLS in front.
• Keep the unifi-data volume (and secret.key / UNIFI_SECRET_KEY) backed up, or stored data becomes unreadable.
• Redirect URIs are restricted to Claude's web callbacks by default; override with UNIFI_OAUTH_REDIRECT_URIS.

All variables are optional: UNIFI_PUBLIC_URL, UNIFI_SECRET_KEY, UNIFI_TENANT_STORE, UNIFI_RP_NAME, UNIFI_ONBOARD_CODE, UNIFI_OAUTH_REDIRECT_URIS (see .env.example).

Claude integration

Remote connector (no local config file)

Run the HTTP endpoint (docker compose up -d), expose it (ideally behind HTTPS), then in Claude add a custom connector: paste the MCP server URL https://<your-host>/mcp. For the single-tenant server no OAuth is needed; for the multi-tenant service paste the client_id/client_secret from onboarding into the connector's OAuth fields.

Claude Desktop (via mcp-remote)

To bridge the remote endpoint into Claude Desktop's config instead:

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

Claude Desktop / Claude Code (stdio)

Run the container or uv directly over stdio:

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "UNIFI_API_KEY=your-key",
        "-e", "UNIFI_CONSOLE_ID=900A6F...:123456789",
        "unifi-mcp"
      ]
    }
  }
}

Project structure

src/unifi_mcp/
  server.py               # MCP server and tool definitions (143 tools)
  client.py               # Site Manager API client (cloud)
  formatting.py           # Site Manager response formatters
  mobility_client.py      # Mobility API client (cloud)
  mobility_formatting.py  # Mobility response formatters
  network_client.py       # Network API client (cloud connector or local)
  network_formatting.py   # Network response formatters
  protect_client.py       # Protect API client (cloud connector or local)
  protect_formatting.py   # Protect response formatters
  tenant.py               # Multi-tenant: encrypted store, client bundles, registry
  oauth.py                # Multi-tenant: OAuth 2.1 authorization-server provider
  web.py                  # Multi-tenant: onboarding UI + combined ASGI app

License

MIT