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.

Related MCP server: UniFi MCP Server

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:

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.

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.