unifi-mcp

A Model Context Protocol server for the UniFi Local Network Integration API. Query your UniFi network from Claude Desktop, Claude Code, Cursor, or any MCP client.

Status

Phase 1 — read-only, four generic tools, spec-driven interface generated at runtime from the UniFi OpenAPI spec.

How it works

The server fetches the OpenAPI spec from your gateway at startup (or uses a bundled fallback) and derives all tool behaviour from it — there is no per-resource code. Adding a new UniFi entity or operation requires no code change; it becomes available as soon as the updated spec is fetched.

The four tools follow a discover-then-query pattern:

| Tool | Purpose | | ----------------------- | ------------------------------------------------------------- | | unifi_list_entities | List available entities (derived from OpenAPI tags) | | unifi_describe_entity | Operations, parameters, and fields for one entity | | unifi_get | Invoke a read (GET) operation on an entity | | unifi_invoke | Invoke a write operation — disabled until write support ships |

The agent calls unifi_list_entities to discover what is available, then unifi_describe_entity on an entity to learn its operations and field names, then unifi_get to retrieve data.

Read-only by default

unifi_invoke is defined and registered but gated: it returns an error unless UNIFI_ALLOW_WRITES=true is set. The default is read-only. Write support will ship in a later phase.

Spec resolution

The server resolves the OpenAPI spec in order:

1. Fresh local cache (age < UNIFI_SPEC_FRESHNESS_MS, default 24 h)
2. Live fetch from the gateway (UNIFI_BASE_URL/proxy/network/integration/v1)
3. Stale local cache (if the live fetch fails)
4. Bundled spec (shipped with the package as a last-resort fallback)

Run pnpm update-spec to update the bundled spec from a live gateway.

Configuration

Copy .env.example to .env and fill in the required values.

| Variable | Required | Default | Description | | ------------------------- | -------- | -------------------- | ------------------------------------------------------ | | UNIFI_BASE_URL | yes | — | Gateway address, e.g. https://192.168.1.1 | | UNIFI_API_KEY | yes | — | Integration API key (see below) | | UNIFI_CA_CERT | no | — | Path to the controller's CA certificate (PEM) | | UNIFI_INSECURE_TLS | no | false | Disable TLS verification — last resort only | | UNIFI_ALLOW_WRITES | no | false | Enable write operations via unifi_invoke | | UNIFI_TIMEOUT_MS | no | 30000 | Per-request timeout in milliseconds | | UNIFI_SPEC_URL | no | — | Override the OpenAPI spec URL fetched from the gateway | | UNIFI_SPEC_FILE | no | — | Use a local spec file as the bundled fallback | | UNIFI_CACHE_DIR | no | ~/.cache/unifi-mcp | Where the cached spec is written | | UNIFI_SPEC_FRESHNESS_MS | no | 86400000 | Max age of the cached spec in milliseconds | | UNIFI_LOG_LEVEL | no | error | Pino log level (error, warn, info, debug) |

Getting an API key

In the UniFi Network application: Settings → Integrations → Add Integration. Copy the generated key into UNIFI_API_KEY.

TLS

UniFi gateways use self-signed certificates. The recommended approach is to pin the controller's CA certificate:

UNIFI_CA_CERT=/path/to/controller-ca.pem

Export the certificate from the UniFi console or your browser and provide the path above. This keeps TLS verification enabled.

UNIFI_INSECURE_TLS=true disables certificate verification entirely. Use it only as a last resort — it exposes connections to man-in-the-middle attacks. The server prints a warning to stderr on startup when it is set.

Running

pnpm install
pnpm build
node dist/cli.js      # or: unifi-mcp (after npm install -g @robinbowes/unifi-mcp)

Note: The package is published as @robinbowes/unifi-mcp (scoped), but the CLI command is unifi-mcp — unchanged.

For use with an MCP client, point the client at the binary with stdio transport.

Development

pnpm install
pnpm dev              # run from source with stdio transport
pnpm test             # unit + component tests
pnpm verify           # format + lint + typecheck + test
pnpm update-spec      # refresh the bundled spec from a live gateway
pnpm smoke            # build, then exercise the tools against a live controller (.env)

Smoke test

pnpm smoke builds the server and drives it as a real MCP client over stdio against the controller configured in your .env. It fetches the live spec, lists and describes entities, runs a couple of read queries, and confirms the read-only gate refuses a write. It is read-only: nothing on the network is changed, and the API key is never printed.

Licence

MIT.