UniFi Network MCP Server

An MCP (Model Context Protocol) server that exposes the UniFi Network Integration API as tools for Claude and other MCP clients: sites, devices, clients, networks, WiFi, firewalls, ACLs, switching, DNS policies, hotspot vouchers, VPNs, and more.

Prerequisites

• Node.js in the range engines.node in package.json allows

• A UniFi Network console with the Integration API enabled

• An API key generated from your UniFi Network console (see Choosing an API key)

Related MCP server: UniFi MCP

Setup

Quick start (Claude Code)

Add to Claude Code with a single command — no clone or build needed:

claude mcp add-json unifi-network '{"command":"npx","args":["-y","@owine/unifi-network-mcp@latest"],"env":{"UNIFI_NETWORK_HOST":"192.168.1.1","UNIFI_NETWORK_API_KEY":"your-api-key"}}' -s user

Use -s user for global availability across all projects, or -s project for the current project only.

@latest runs the newest release every time the server starts, including a new major version. To take fixes but choose when to make breaking upgrades, pin the major version instead (for example @owine/unifi-network-mcp@3).

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop:

{
  "mcpServers": {
    "unifi-network": {
      "command": "npx",
      "args": ["-y", "@owine/unifi-network-mcp@latest"],
      "env": {
        "UNIFI_NETWORK_HOST": "192.168.1.1",
        "UNIFI_NETWORK_API_KEY": "your-api-key"
      }
    }
  }
}

Manual configuration (Claude Code)

Alternatively, add the same "unifi-network" entry to your ~/.claude.json under the top-level "mcpServers" key.

From source

If you prefer to build locally, this project uses pnpm — use pnpm install, not npm install, which ignores pnpm-lock.yaml and resolves different dependency versions. Node 25 and later no longer bundle Corepack, so install pnpm itself if you don't have it; it switches to the version packageManager in package.json pins:

git clone https://github.com/owine/unifi-network-mcp.git
cd unifi-network-mcp
npm install -g pnpm   # if pnpm is not installed
pnpm install
pnpm run build

Then add to Claude Code:

claude mcp add-json unifi-network '{"command":"node","args":["/path/to/unifi-network-mcp/dist/index.js"],"env":{"UNIFI_NETWORK_HOST":"192.168.1.1","UNIFI_NETWORK_API_KEY":"your-api-key"}}' -s user

Environment Variables

UniFi consoles ship with a self-signed certificate, so against a local console the first call usually fails with a certificate error. The safe fix is to trust that one certificate: save it and point UNIFI_NETWORK_CA_CERT at the file.

openssl s_client -connect 192.168.1.1:443 </dev/null 2>/dev/null | openssl x509 > ~/.config/unifi-console.pem

Set UNIFI_NETWORK_CA_CERT to the file's absolute path (for example /home/you/.config/unifi-console.pem); MCP hosts do not expand ~ in env. The server then accepts that exact certificate even though it is issued to a name like unifi.local rather than the IP you connect to, and whether it is self-signed or issued by a private CA; any other certificate must chain to the file or to a publicly trusted CA and match the hostname. Pinning does not lift a certificate's validity dates. Check the fingerprint (openssl x509 -in ~/.config/unifi-console.pem -noout -fingerprint -sha256) against the console's if the network between you is not trusted. If the console later generates a new certificate, save it again.

Setting UNIFI_NETWORK_VERIFY_SSL=false instead turns off certificate checks for this server's connections to the console: anyone who can intercept that traffic can then read the API key. Only do this on a network you trust.

Behind an HTTP(S) proxy, set NODE_USE_ENV_PROXY=1 along with HTTPS_PROXY (and NO_PROXY for anything to reach directly), as for Node's own fetch; the console's certificate is still verified through the proxy.

Choosing an API key

The key carries the rights of the admin who created it, and this server is driven by a model that reads data other people control (client hostnames, device names). Create the key as a dedicated admin with the least role that covers your use: for the default read-only mode, a View Only admin, so nothing can be changed even if a tool were misused. Use a full-access admin only when you set UNIFI_NETWORK_READ_ONLY=false, and then also read Limiting write mode.

Cloud Connector

To use a Site Manager API key with a console, set UNIFI_NETWORK_HOST=api.ui.com and UNIFI_NETWORK_CONSOLE_ID to its console ID. The existing UNIFI_NETWORK_API_KEY supplies the key. This works for current Integration API tools and the controller history and classic routes when permitted by the console/key. Cloud Connector requires eligible console ownership/access and firmware 5.0.3 or later. TLS verification stays on: the server refuses to start with UNIFI_NETWORK_VERIFY_SSL=false and api.ui.com.

References: official Cloud Connector API and the Art-of-WiFi controller client, whose session queries use epoch seconds.

Upgrading from 2.x

3.0 tightens several defaults. Most setups need no change; check these:

• Cloud Connector with UNIFI_NETWORK_VERIFY_SSL=false: the server now refuses to start with UNIFI_NETWORK_HOST=api.ui.com and verification off. Unset UNIFI_NETWORK_VERIFY_SSL.

• Writes that open access need confirm: true: creating, enabling or switching a firewall policy or ACL rule to ALLOW, disabling a blocking policy or rule, changing what an enabled policy or rule matches, a reorder that moves an ALLOW ahead of a BLOCK, creating or enabling an open SSID or changing its network, captive portal, client isolation or client filtering, changing an SSID's security type, and creating a large batch of vouchers. Without it the tool returns an error naming the change, and the agent can ask you before re-invoking. A dry run of such a change says why in confirmationRequired.

• IDs must be IDs: ID inputs accept only letters, digits, - and _ (pass the IDs that list and get tools return).

• Smaller default results: unifi_list_client_sessions and unifi_list_vouchers return fewer rows by default, and unifi_list_client_history now returns at most limit clients, most recently seen first, with totalCount and truncated; pass limit for more. Rows from both history tools carry only the fields their tool descriptions list.

• Compact text output: tool results are compact JSON rather than indented; structuredContent is unchanged.

• Writes that could let traffic in from the WAN are refused: with writes enabled, a firewall policy that allows traffic from the External zone, a change to that zone or to which networks are in it, putting a network in a zone such a policy targets, a reorder of its policies, or an edit to a traffic matching list such a policy uses now fails even with confirm: true (see WAN-exposure refusals). Set UNIFI_NETWORK_ALLOW_WAN_EXPOSURE=true to go back to needing only confirm.

• Only the endpoints the tools use: every request is checked against an allowlist before it is sent. No tool behaves differently; anything else is refused.

One rule is relaxed: a dryRun: true preview of a destructive tool no longer needs confirm.

Safety Features

This server provides layered safety controls for responsible operation:

• Tool annotations — Every tool declares readOnlyHint, destructiveHint and openWorldHint, and every write tool idempotentHint, so MCP clients (like Claude Code) can make informed confirmation decisions

• Server instructions — On connect the server gives the MCP host a short usage guide for the model (get a siteId first, page with offset/limit, preview writes with dryRun, ask before passing confirm), matched to read-only or read-write mode

• Read-only mode — Enabled by default. Only read operations (list, get) are registered. Set UNIFI_NETWORK_READ_ONLY=false to enable write/mutating tools

• Destructive tool warnings — Tools that delete or irreversibly modify resources have descriptions prefixed with DESTRUCTIVE: to clearly signal risk

• Confirmation parameter — Every tool marked DESTRUCTIVE: (including unifi_remove_device and unifi_bulk_delete_vouchers) requires an explicit confirm: true parameter for the call to succeed. A dryRun: true preview does not need it, since it changes nothing

• Confirmation for changes that open access — Some routine write tools ask for confirm: true only when a particular change can let traffic or guests in: a firewall policy or ACL rule that ALLOWs traffic (created, switched on, or switched to ALLOW), disabling a policy or rule that blocks, changing what an enabled policy or rule matches (widening an ALLOW and narrowing a BLOCK both let more through), a reorder that moves an ALLOW ahead of a BLOCK it used to follow, creating or switching on an open SSID or changing an open SSID's network, captive portal, client isolation or client filtering, changing an SSID's security type, and creating a large batch of vouchers (unifi_create_voucher's confirm parameter states the threshold). Each is judged on the resource as the change would leave it, so the update, patch and reorder tools read it first. Without it the call returns an error naming the change; a dry run never needs it, and reports the reason in confirmationRequired

• Dry-run support — Every write tool accepts an optional dryRun: true parameter that returns a preview of the HTTP request (method, path, body) without making any changes

• Safe partial updates — The UniFi PUT endpoints for WiFi broadcasts, networks, firewall policies, ACL rules and DNS policies replace the whole resource, and some fields reset when omitted (a missing dhcpGuarding disables DHCP guarding). Their update tools read the current resource, keep every documented body field, and overlay only the top-level fields you pass, so omitted fields keep their current values. A field you pass replaces the current one whole — nested objects such as ipv4Configuration, securityConfiguration or a policy's source are not deep-merged, so start from what the get tool returns. Pass null to clear an optional field. Parallel updates to one resource run one at a time. The dry-run preview shows the merged body (the read still happens)

• Secret redaction — WiFi passphrases (including per-VLAN PPSK keys) are returned as [REDACTED] unless the caller passes includeSecrets: true to unifi_list_wifi / unifi_get_wifi. Write-tool echoes and dry-run previews are always redacted, and an update that echoes back [REDACTED] keeps the stored passphrase

• Request allowlist — Every request the server makes, reads included, is checked before it is sent against a fixed list of the methods and paths the tools use. Anything else, such as a path with .. or encoded characters, another application on the console, or a write the server is not set up to make, is refused and never reaches the console

• Operator limits for write mode — UNIFI_NETWORK_WRITE_TOOLS loads only the write tools you name, writes that could let traffic in from the WAN are refused outright, and UNIFI_NETWORK_WRITE_LOG keeps a record of every write call. See Limiting write mode

Limiting write mode

An agent with write access reads data that other people control: client hostnames, device names, SSIDs, notes on vouchers. Any of it can be written to look like an instruction, and a model can be misled by it. dryRun and confirm help when the model behaves, but they are inputs the model itself supplies. The settings below are yours: they hold whatever the model is told, because the server enforces them before anything reaches the console.

Turning writes on

1. Use a dedicated, least-privilege key. Create a separate admin for the agent, limited to the Network application and to the sites it should manage, and generate the key as that admin. Do not reuse your own key.

2. Enable writes: set UNIFI_NETWORK_READ_ONLY=false.

3. Load only the write tools the job needs: set UNIFI_NETWORK_WRITE_TOOLS, for example unifi_create_voucher,unifi_delete_voucher for a front desk, or wifi for SSID changes. Other write tools are not registered, so the agent never sees them, and the request allowlist refuses their requests as well.

4. Keep the WAN-exposure refusals on: leave UNIFI_NETWORK_ALLOW_WAN_EXPOSURE unset.

5. Name your WAN zone: set UNIFI_NETWORK_WAN_ZONE_IDS to the ID of each site's External zone. While the server is still read-only, ask the agent to run unifi_list_firewall_zones for each site and copy the id of the External zone (system-defined, metadata.origin SYSTEM_DEFINED). Without the list the server recognises that zone by its name, which can be changed.

6. Turn on the write log and watch it: set UNIFI_NETWORK_WRITE_LOG to an absolute path, for example /home/you/.local/state/unifi-mcp/writes.jsonl, and look at it after a session (tail -f works).

7. Try changes with dryRun: true first: ask the agent to preview a change, check the request, then let it run.

A Claude Desktop entry with all of this set:

{
  "mcpServers": {
    "unifi-network": {
      "command": "npx",
      "args": ["-y", "@owine/unifi-network-mcp@latest"],
      "env": {
        "UNIFI_NETWORK_HOST": "192.168.1.1",
        "UNIFI_NETWORK_API_KEY": "key-of-the-agent-admin",
        "UNIFI_NETWORK_CA_CERT": "/home/you/.config/unifi-console.pem",
        "UNIFI_NETWORK_READ_ONLY": "false",
        "UNIFI_NETWORK_WRITE_TOOLS": "unifi_create_voucher,unifi_delete_voucher,wifi",
        "UNIFI_NETWORK_WAN_ZONE_IDS": "6f1c2a52-3b6d-4a8e-9a0b-2d5e8f7c1a90",
        "UNIFI_NETWORK_WRITE_LOG": "/home/you/.local/state/unifi-mcp/writes.jsonl"
      }
    }
  }
}

Write tool limits

UNIFI_NETWORK_WRITE_TOOLS takes write tool names from the Tools tables and group names, which match the tool modules: devices, clients, networks, wifi, hotspot, firewall, acl, dns-policies, traffic-matching. Unset, every write tool loads, as before. none or an empty value loads none, leaving a read-only tool set while the request allowlist still refuses writes. An unknown name stops the server with a configuration error listing the valid names. Read tools are never affected. The server instructions tell the model which write tools are available.

WAN-exposure refusals

With writes enabled, the server refuses these changes, whatever confirm says, and sends nothing:

• creating, updating or patching a firewall policy so that it allows traffic (any action but BLOCK or REJECT) from the WAN zone. A policy whose connectionStateFilter lists only ESTABLISHED and/or RELATED is exempt, since it only lets return traffic back in; a missing or empty filter matches every state, so it is not. An update is judged on the full body after merging, and a patch on the policy as the patch would leave it (a patch that only turns logging or flow reporting on or off, or disables the policy, is not checked)

• changing the WAN zone (its name or networks), deleting it, or moving networks out of it into another zone

• creating or updating a network so that it is in the WAN zone, or moving a network out of it

• putting a network in a zone that a policy allowing traffic from the WAN targets (creating or updating a network with that zoneId, or adding networks to that zone), since the network becomes reachable from the WAN without any policy changing. This holds even when the policy's destination trafficFilter narrows it to particular hosts, as the server cannot tell whether those hosts are on the network being moved

• reordering the policies for traffic from the WAN zone, which could put an allow ahead of a block

• updating a traffic matching list that a policy allowing traffic from the WAN uses, since the list decides what that policy lets in

Blocking traffic from the WAN, and allowing traffic from inside to the WAN, are not affected. A dry run runs the same check and reports the refusal. ACL rules are not checked: they are enforced by switches between LAN hosts and have no zone, so they cannot let WAN traffic past the gateway firewall. The Integration API has no port-forwarding endpoint.

The Integration API marks zones only as system- or user-defined, and zone names can be changed, so a zone counts as the WAN when its ID is in UNIFI_NETWORK_WAN_ZONE_IDS, or when it is system-defined and named External (in any case). Set the ID list: a renamed External zone is otherwise missed. To check a change the server lists the site's firewall zones (and, for a matching list or a network put in a zone, its policies). If that fails, or the change names a zone that is not in the list, the write is refused rather than allowed unchecked.

A refused call returns:

Refused: the policy would ALLOW traffic from the External zone, which is the WAN. This server does not make changes that could let traffic in from the WAN, and confirm does not override this; if the change is intended, make it in the UniFi console.

If you do want the agent to make such changes, UNIFI_NETWORK_ALLOW_WAN_EXPOSURE=true turns the refusals off; those changes then need confirm: true like other changes that open access.

Write log

With UNIFI_NETWORK_WRITE_LOG set, each write tool call appends one line, including dry runs and refused calls. Read tools are not logged.

{"ts":"2026-10-19T00:12:46.170Z","tsLocal":"2026-10-18T20:12:46.170-04:00","tool":"unifi_create_firewall_policy","args":{"siteId":"5f3a9c1e-2b7d-4e8f-9a6b-0c1d2e3f4a5b","policy":{"name":"SSH in","enabled":true,"action":{"type":"ALLOW"},"source":{"zoneId":"6f1c2a52-3b6d-4a8e-9a0b-2d5e8f7c1a90"},"destination":{"zoneId":"0b6d9c1e-58a4-4f43-8e0f-1c2d3e4f5a6b"}},"confirm":true},"method":"POST","path":"/integration/v1/sites/5f3a9c1e-2b7d-4e8f-9a6b-0c1d2e3f4a5b/firewall/policies","dryRun":false,"outcome":"refused","reason":"wan_exposure","durationMs":29}

outcome is ok (with the HTTP status), dry_run, refused (with a reason: request_guard, wan_exposure or confirmation_required) or error (with the HTTP status when the console answered). path is the path under the Network application, without host, console ID or query string; method and path are null when the call stopped before choosing a request. Arguments are redacted: WiFi passphrases (including each presharedKeys[] entry's, which keeps its network), and any field named, in any case, passphrase, password, secret, sharedSecret, radiusSecret, their legacy x_ forms, apiKey, api_key, apiToken, token, accessToken, refreshToken, authToken, privateKey, private_key or presharedKey. The list is in src/write-log.ts. The API key and the console's response bodies are never written.

The file is created with mode 0600, and missing parent directories with 0700. The server refuses to start if the path is a symlink, not a regular file, has other hard links, or is writable by group or others. On Windows, where Node reports every writable file as mode 0666 and cannot open without following symlinks, only the symlink and regular-file checks apply: restrict the file with its ACL (for example, keep it in your user profile). If a line cannot be written (a full disk, say), the tool call still completes and the server reports the problem once on stderr.

Structured Output

Every read tool, and every write tool whose API response returns the affected resource, declares an MCP outputSchema and returns structuredContent alongside the usual text content. Clients that understand structured output get typed, machine-readable results instead of parsing JSON out of a text blob. A dryRun: true call returns its preview, {"dryRun": true, "wouldExecute": {"method", "path", "body"}}, the same way. Other write tools (deletes, device and guest actions, reorders) return the API response as text only.

The schemas live in src/utils/output-schemas.ts. They deliberately use a loose strategy: every non-key field is optional and objects accept fields the schema does not list, so firmware- and hardware-specific fields flow through unchanged rather than being stripped or triggering a validation error. This keeps the contract stable across console versions and hardware models.

Tools

System

Sites

Devices

Clients

Client history

Classic controller API

Internet exposure

Networks

WiFi

Hotspot Vouchers

Firewall Zones & Policies

ACL Rules

Switching

DNS Policies

Traffic Matching

Supporting

Retained client connections

The Integration API only lists connected clients. The two history tools use the controller APIs instead: GET /proxy/network/v2/api/site/{siteReference}/clients/history and POST /proxy/network/api/s/{siteReference}/stat/session. The POST is a statistics query and does not change the network. Both tools remain available in read-only mode.

Use internalReference from unifi_list_sites (often default), not its UUID. Session queries require start and end in Unix seconds, with a maximum 31-day window. The controller ignores _start/offset on this endpoint. A full result sets mayBeTruncated=true; split the time window or filter by MAC and query again. Overlap split boundaries and deduplicate session IDs. A result below the requested limit means the query was not capped, not that all dates were retained.

{"siteReference":"default","start":1789272000,"end":1789876800}

unifi_list_client_history lists offline clients only, most recently seen first, up to limit, with totalCount. truncated: true means less recently seen clients were left out; raise limit (narrowing withinHours drops those same clients).

Rows keep the controller's field names (assoc_time, duration, rx_bytes, tx_bytes, roaming_sessions, …) but carry only the fields each tool's description lists. RX/TX are the controller's counters, not relabeled client download/upload. Inventory is separate from session history. Retention varies; a non-truncated result does not prove all requested dates were retained, and ongoing sessions may not be present. Neither association nor traffic counters establish end-to-end Internet success.

These controller routes are not part of the published Integration API contract. Their availability and API-key permissions vary by controller version. Unsupported, unauthorized, HTML login, legacy meta.rc error and malformed responses fail explicitly instead of becoming an empty history. History requests are time-limited, reject redirects, and refuse oversized responses. No browser cookies are required where API-key access is supported.

Classic controller reads

Legacy firewall rules, and the firewall groups and networks they reference, are not in the Integration API. Three read tools list them from the classic controller API instead: GET /proxy/network/api/s/{siteReference}/rest/networkconf, /rest/firewallgroup and /rest/firewallrule. Like the history tools they take the site's internalReference from unifi_list_sites, and remain available in read-only mode. No classic write is allowlisted.

Each collection is returned whole; the controller does not page it. Legacy rules are sorted by ruleset, then rule_index, the order they are evaluated in. Records keep the controller's field names and their classic _ids, which differ from Integration API IDs, so an ID from one API cannot be passed to a tool of the other. Legacy rules reference networks by unifi_list_classic_networks IDs and groups by unifi_list_firewall_groups IDs. On a site that uses the zone-based firewall, legacy rules may not be enforced; its rules are the firewall policies.

Classic network records hold WAN, VPN and RADIUS credentials. Rows are therefore built from a fixed list of fields per tool (its output schema, in src/utils/output-schemas.ts), never by redacting the record, so a credential under any name is never returned. Errors are reported the same way as for the history routes.

Internet exposure

Port forwards, UPnP and device SSH settings are not in the Integration API, so the exposure tools read the classic controller API: GET /proxy/network/api/s/{siteReference}/rest/portforward and /proxy/network/api/s/{siteReference}/get/setting, directly or through the Cloud Connector. Like the history tools they take the site's internalReference from unifi_list_sites and remain available in read-only mode. No classic write is allowlisted.

Settings sections hold credentials (SSH passwords, management and cloud-access keys, RADIUS secrets), so every result is built from a fixed list of fields (its output schema, in src/utils/output-schemas.ts), never by redacting the record. SSH keys are counted, not returned.

A setting this controller version does not have comes back as status: "unavailable" with a detail saying what was looked for. It never means the feature is off. UPnP is read from a upnp settings section where there is one, otherwise from the gateway (usg) section's upnp_* fields, and source says which; Network 11.0.94 has no upnp section. upnp_nat_pmp_enabled is the stored setting, which does nothing while UPnP is off, and detail says so when the two disagree.

Remote Access and console (UniFi OS) SSH are UniFi OS settings outside this API, so unifi_get_device_ssh_settings reports device SSH only. Which internal networks can reach the console's web UI is decided by the firewall rules or policies.

Troubleshooting

Configuration errors go to the MCP host's server log and the server exits. Tool errors reach the agent as results starting with Error:.

Development

pnpm install            # Install dependencies
pnpm run build          # Compile TypeScript
pnpm start              # Run the server
pnpm run typecheck      # Type-check src/ and tests
pnpm run lint           # ESLint
pnpm run lint:fix       # ESLint with auto-fix
pnpm test               # Run all tests (vitest)
pnpm run test:watch     # Run tests in watch mode
pnpm run test:coverage  # Run tests with coverage
pnpm run test:package   # Build, pack and smoke-test the published package

Commit conventions

This project uses conventional commits in pull request titles and release-drafter for releases. Pull requests are squash-merged, so the title is the commit subject:

• feat: ... — new feature (minor version bump)

• fix: ... — bug fix (patch version bump)

• deps: ... — dependency update (patch version bump)

• feat!: ... — breaking change (major version bump); the ! must be in the title, a BREAKING CHANGE: footer is not read

• chore:, docs:, ci:, etc. — no version bump

Every push to main updates a draft GitHub Release with the next version and its notes. A maintainer publishes the draft, which builds, tests and publishes that tagged commit to npm with provenance. To release a different version, edit the draft's tag and title before publishing. Release notes after 3.0.0 are in GitHub Releases; CHANGELOG.md covers 3.0.0 and earlier.

License

MIT — see LICENSE.