unifi-network-mcp

MCP server for the official UniFi Network Integration API.

Gives AI assistants (Claude, and any MCP-compatible client) typed, safety-gated access to your UniFi Network console: devices, clients, networks, WiFi, firewall policies and zones, ACL rules, DNS policies, traffic matching lists, hotspot vouchers, switching views, and supporting resources — the complete documented v10.4.57 surface, 73 operations behind 15 tools.

Community project. Not affiliated with, endorsed by, or supported by Ubiquiti Inc. "UniFi" is used only to describe what this software connects to.

Quick start

Create an API key: sign in at unifi.ui.com → Settings → API Keys → Create New API Key. Store it securely — it is shown once.
Add the server to your MCP client. For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "unifi-network": {
      "command": "npx",
      "args": ["-y", "@zenixsolutions/unifi-network-mcp"],
      "env": {
        "UNIFI_CONSOLE_URL": "https://192.168.1.1",
        "UNIFI_API_KEY": "<your API key>",
        "UNIFI_INSECURE": "1"
      }
    }
  }
}

Ask your assistant something like "list the clients on my UniFi network".

Configuration

Variable	Required	Meaning
`UNIFI_CONSOLE_URL`	yes	Console base URL, e.g. `https://192.168.1.1`. The integration path (`/proxy/network/integration`) is appended automatically. The documented Site Manager Connector base on `api.ui.com` also works — no VPN needed.
`UNIFI_API_KEY`	yes	API key from unifi.ui.com. Sent as the `X-API-KEY` header.
`UNIFI_INSECURE`	no	Set to `1` to accept the console's self-signed TLS certificate. A warning is printed on every start. See SECURITY.md for the trade-off.

Verify a configuration without connecting a client:

npx -y @zenixsolutions/unifi-network-mcp --check   # exit 0 ok, 78 misconfigured
npx -y @zenixsolutions/unifi-network-mcp --list-tools
npx -y @zenixsolutions/unifi-network-mcp --version

The tool surface

15 tools cover all 73 documented operations (measured tools/list cost: ≈6,800 tokens). Each resource area is one tool with an operation argument:

unifi_info, unifi_sites, unifi_devices, unifi_clients, unifi_networks, unifi_wifi_broadcasts, unifi_firewall_policies, unifi_firewall_zones, unifi_acl_rules, unifi_dns_policies, unifi_traffic_matching_lists, unifi_vouchers, unifi_switching, unifi_supporting — plus unifi_spec, which returns the vendor's exact request/response schema for any operation.

Full per-operation reference: docs/tools.md.

Safety model

Every operation is classified Read / Create / Update / Admin / Destructive in its tool description.
Destructive (all deletes, device removal) and Admin (device restart, PoE power-cycle, guest authorization) operations require confirm: true in the call — an assistant cannot trigger them by accident.
Request bodies are validated locally against Ubiquiti's own published OpenAPI schemas before anything is sent.
The real write control is your API key's permissions — scope the key in unifi.ui.com to what you actually want an assistant to do. The server adds friction, not authorization.
The API key is never logged and is redacted from every error message.

Documentation

docs/tools.md — tool and operation reference
docs/compatibility.md — clients, controller versions, transports, known limitations
docs/reference/openapi.json — the committed vendor contract (v10.4.57) this build is generated from
SECURITY.md — security posture, residual risks, reporting
CHANGELOG.md — release notes

Development

npm install
npm run generate      # regenerate op map from docs/reference/openapi.json
npm run typecheck && npm run lint && npm test
npm run build
npm run check:budget  # measured tools/list token budget (CI-enforced)
UNIFI_CONSOLE_URL=... UNIFI_API_KEY=... npm run test:contract  # live, read-only

See CONTRIBUTING.md. Governance follows the Engineering OS framework; the foundation decisions are recorded in docs/rfc/RFC-004-unifi-network-mcp-foundation.md.

License

MIT

unifi-network-mcp