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 (a static-inference draft, shipped with the package as a last-resort fallback)

Run pnpm update-spec to refresh the bundled spec from the community OpenAPI mirror, which is pinned to a commit and checked against a recorded SHA-256 before it is parsed.

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.

Installing in an MCP client

The transport is stdio: the client spawns the binary and speaks MCP over its stdin/stdout. The server reads configuration from the process environment only — it does not load .env — so the gateway address and API key must come from the client's own config block.

Claude Code

claude mcp add unifi -s user \
  -e UNIFI_BASE_URL=https://192.168.1.1 \
  -e UNIFI_API_KEY=your-integration-api-key \
  -- npx -y @robinbowes/unifi-mcp

-s user makes the server available in every project; -s local (the default) limits it to the current one. Avoid -s project with a literal key — that scope writes to .mcp.json, which is committed. Confirm with claude mcp list.

A global install drops the npx resolution from every launch:

npm install -g @robinbowes/unifi-mcp
claude mcp add unifi -s user \
  -e UNIFI_BASE_URL=https://192.168.1.1 \
  -e UNIFI_API_KEY=your-integration-api-key \
  -- unifi-mcp

Claude Desktop

Add an entry to claude_desktop_config.json and restart the app. It lives in ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows.

{
    "mcpServers": {
        "unifi": {
            "command": "/usr/local/bin/node",
            "args": ["/usr/local/lib/node_modules/@robinbowes/unifi-mcp/dist/cli.js"],
            "env": {
                "UNIFI_BASE_URL": "https://192.168.1.1",
                "UNIFI_API_KEY": "your-integration-api-key"
            }
        }
    }
}

If the file already exists, merge the unifi key into the existing mcpServers object — pasting the block over the whole file drops any other servers you have configured.

Use absolute paths. Claude Desktop is a GUI application and does not inherit a login shell's PATH, so a bare node, npx, or unifi-mcp fails to spawn. command -v node and npm root -g give the paths for your machine.

Other stdio clients take the same command/args/env shape — Cursor and Windsurf under mcpServers, Zed under context_servers.

From a local checkout

pnpm install && pnpm build
claude mcp add unifi-dev \
  -e UNIFI_BASE_URL=https://192.168.1.1 \
  -e UNIFI_API_KEY=your-integration-api-key \
  -- node /absolute/path/to/unifi-mcp/dist/cli.js

Troubleshooting

For the last two, set UNIFI_LOG_LEVEL=info and read the client's server log: the server logs spec resolved with the source it used, and warns explicitly when it falls back to the bundled spec.

Development

pnpm install
task hooks-install    # install the git hooks (once per clone, and after they change)
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 the pinned mirror
pnpm smoke            # build, then exercise the tools against a live controller (.env)

task hooks-install is not optional bookkeeping: besides the pre-commit and commit-msg checks, the hooks re-run pnpm install --frozen-lockfile after a checkout, merge or rebase, which is what keeps node_modules matching the lockfile for tools that read it directly (tsserver, ALE, node dist/cli.js).

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.