the-real-unifi-mcp

An MCP server that gives Claude (or any MCP client) full read/write access to the UniFi Site Manager and Network APIs over the official cloud endpoint. Cloud-only, stdio transport.

Unofficial project. This server is not affiliated with or endorsed by Ubiquiti Inc. UniFi and Ubiquiti are trademarks of Ubiquiti Inc., used here only to name the API this software works with; see NOTICE.

Point it at a UniFi Site Manager API key and your MCP client can list consoles, inspect devices and clients, and manage networks, WiFi, firewall policies, and more, through 167 tools covering the documented API surface.

Features

• 167 tools across both UniFi APIs, read and write.

• Three-layer tool design: 86 hand-wrappers (10 Site Manager + 76 Network) + 80 auto-generated tools, one per documented endpoint + 1 raw-request escape hatch (86 + 80 + 1 = 167). The tool contract is pinned by tests/contract/tools-contract.json.

• MCP resources and MCP prompts for ready-made workflows.

• Lazy ID discovery (consoleId / Network siteId / Site Manager siteId), cached for the process lifetime.

• Write guard on by default: UNIFI_CONFIRM_WRITES (default true) turns destructive tools into preview-then-confirm; set it to false to execute writes directly. The model itself can send confirm: "YES", so this is a speed bump, not a human approval (see SECURITY.md).

• Secret redaction in the server's own stderr log lines (known key patterns and the configured API key by value).

Related MCP server: UnifiyMe

Requirements

• Node.js >= 22.12.

• UniFi Site Manager API key with Network scope. Create one at unifi.ui.com under Settings → API.

• UniFi Console with firmware ≥ 5.0.3 (required by the Network API).

Installation

From npm (recommended)

No install step is needed: your MCP client starts the server with npx, which fetches the package from npm on first use.

npx -y the-real-unifi-mcp   # starts the server on stdio; needs UNIFI_API_KEY in the environment

Or install it globally and use the the-real-unifi-mcp command:

npm install -g the-real-unifi-mcp

Pin a version (the-real-unifi-mcp@<version>) if you want updates only when you change the config. Releases from v0.2.1 on are published to npm from GitHub Actions with provenance (v0.2.0 is a GitHub release only); npm audit signatures verifies it.

From source

git clone https://github.com/mguttmann/the-real-unifi-mcp.git
cd the-real-unifi-mcp
npm ci
cp .env.example .env
# Edit .env: set UNIFI_API_KEY (Site Manager key with Network scope)
npm run build   # prebuild runs lint, typecheck and unit tests first
npm start       # node dist/index.js; reads .env from the current directory

As MCPB bundle

npm ci
npm run build:mcpb
# Writes release/the-real-unifi-mcp-<version>.mcpb (install it in Claude Desktop) and its SBOM.

Releases from v0.2.0 on attach the .mcpb, the npm tarball, CycloneDX SBOMs and SHA256SUMS; see docs/RELEASING.md.

Configuration

Claude Desktop config

Add to claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "the-real-unifi-mcp"],
      "env": {
        "UNIFI_API_KEY": "<your Site Manager API key>"
      }
    }
  }
}

Any variable from Configuration can go into env. With a source checkout, use "command": "node" and "args": ["--env-file=/absolute/path/to/the-real-unifi-mcp/.env", "/absolute/path/to/the-real-unifi-mcp/dist/index.js"] instead.

Restart Claude Desktop after editing the file. The server exposes its tools under the unifi prefix.

Claude Code config

Register the server with the Claude Code CLI (--scope user makes it available in every project; the default scope, local, keeps it private to you in the current project):

claude mcp add --scope user unifi --env UNIFI_API_KEY="YOUR_SITE_MANAGER_API_KEY" -- npx -y the-real-unifi-mcp

From a source checkout:

claude mcp add --scope user unifi -- node \
  --env-file=/absolute/path/to/the-real-unifi-mcp/.env \
  /absolute/path/to/the-real-unifi-mcp/dist/index.js

claude mcp list shows whether it connects.

Tool reference

Site Manager hand-wrappers (10)

Account-level tools against api.ui.com directly:

• unifi_sm_list_hosts: list all UniFi consoles on the account

• unifi_sm_get_host: detail for a single console

• unifi_sm_list_sites: account-level sites

• unifi_sm_list_devices: account-level device list

• unifi_sm_get_isp_metrics: ISP metrics by bucket (5m/1h)

• unifi_sm_query_isp_metrics: query ISP metrics with a time window

• unifi_sm_list_sdwan_configs: SD-WAN configurations

• unifi_sm_get_sdwan_config: single SD-WAN configuration

• unifi_sm_get_sdwan_config_status: status of an SD-WAN configuration

• unifi_sm_identity: resolved consoleId, networkSiteId, siteManagerSiteId

Network hand-wrappers (76)

Per-console tools via the Cloud Connector proxy, grouped by resource:

• Info / Sites (2): unifi_net_get_info, unifi_net_list_sites

• Devices (9): unifi_net_list_devices, unifi_net_get_device, unifi_net_get_device_stats, unifi_net_list_pending_devices, unifi_net_adopt_devices, unifi_net_device_action, unifi_net_reboot_device, unifi_net_port_action, unifi_net_remove_device

• Clients (5): unifi_net_list_clients, unifi_net_get_client, unifi_net_client_action, unifi_net_block_client, unifi_net_unblock_client (block/unblock return a "not supported" error: the Network API has no such client action)

• Networks (6): unifi_net_list_networks, unifi_net_get_network, unifi_net_get_network_references, unifi_net_create_network, unifi_net_update_network, unifi_net_delete_network

• WiFi broadcasts (5): unifi_net_list_wifi, unifi_net_get_wifi, unifi_net_create_wifi, unifi_net_update_wifi, unifi_net_delete_wifi

• Firewall (13): unifi_net_list_firewall_zones, unifi_net_get_firewall_zone, unifi_net_create_firewall_zone, unifi_net_update_firewall_zone, unifi_net_delete_firewall_zone, unifi_net_list_firewall_policies, unifi_net_get_firewall_policy, unifi_net_create_firewall_policy, unifi_net_update_firewall_policy, unifi_net_patch_firewall_policy, unifi_net_delete_firewall_policy, unifi_net_get_firewall_policy_ordering, unifi_net_reorder_firewall_policies

• ACL rules (7): unifi_net_list_acl_rules, unifi_net_get_acl_rule, unifi_net_create_acl_rule, unifi_net_update_acl_rule, unifi_net_delete_acl_rule, unifi_net_get_acl_rule_ordering, unifi_net_reorder_acl_rules

• DNS policies (5): unifi_net_list_dns_policies, unifi_net_get_dns_policy, unifi_net_create_dns_policy, unifi_net_update_dns_policy, unifi_net_delete_dns_policy

• Traffic matching lists (5): unifi_net_list_traffic_lists, unifi_net_get_traffic_list, unifi_net_create_traffic_list, unifi_net_update_traffic_list, unifi_net_delete_traffic_list

• Hotspot vouchers (5): unifi_net_list_vouchers, unifi_net_get_voucher, unifi_net_create_vouchers, unifi_net_delete_voucher, unifi_net_delete_vouchers

• Switching (6): unifi_net_list_switch_stacks, unifi_net_get_switch_stack, unifi_net_list_mclag_domains, unifi_net_get_mclag_domain, unifi_net_list_lags, unifi_net_get_lag

• Supporting (8): unifi_net_list_wans, unifi_net_list_site_to_site_vpn, unifi_net_list_vpn_servers, unifi_net_list_radius_profiles, unifi_net_list_device_tags, unifi_net_list_dpi_application_categories, unifi_net_list_dpi_applications, unifi_net_list_countries

Auto-generated tools (80)

Named unifi_gen_<docpage> (e.g. unifi_gen_createfirewallpolicy, unifi_gen_getinfo). One tool per documented UniFi API endpoint. siteId is auto-resolved from discovery; callers do not need to pass it. See src/tools/generated/ for the full inventory.

Escape hatch (1)

unifi_raw_request(method, path, body?, query?): execute any HTTP method against api.ui.com{path}. The path must be relative; see SECURITY.md for what is refused. Auth, retry, error parsing, and pagination hints are handled automatically. Useful when no dedicated tool exists.

Resources

• unifi://identity: resolved consoleId + both siteIds + console metadata

• unifi://hosts: account hosts list

• unifi://hosts/{id}: single host detail

Prompts

• unifi-audit-firewall: walks firewall zones and policies, flags weak rules, suggests hardening

• unifi-network-health: WAN status, online/offline device counts, top clients by activity

• unifi-adoption-status: pending adoptions report with adopt/reject recommendation

Write safety

By default (UNIFI_CONFIRM_WRITES unset or true), destructive tools require an explicit confirm: "YES" argument; without it they return a preview in which passwords, WiFi passphrases, pre-shared keys, secrets, tokens and keys in the body are replaced by (redacted). Set UNIFI_CONFIRM_WRITES=false to let destructive tools execute directly:

{
  "data": {
    "preview": {
      "tool": "unifi_net_create_vouchers",
      "method": "POST",
      "url": "/v1/connector/consoles/.../proxy/network/integration/v1/sites/.../hotspot/vouchers",
      "body": { "count": 1, "name": "demo" }
    },
    "hint": "Write confirmation is on (UNIFI_CONFIRM_WRITES). Re-run with `confirm: \"YES\"` to apply this change."
  }
}

The model can send confirm: "YES" on its own, so the guard is a second step for the model, not a human approval. If you want to approve each write yourself, keep your MCP client's per-tool approval on for the write tools (all of them carry destructiveHint: true).

Examples

Prompts you can paste into Claude after installing the server:

• "Show me all my UniFi networks and their VLAN IDs."

• "Which of my UniFi devices are offline right now?"

• "Audit my firewall posture: group rules by zone and flag any allow-any-any."

• "Reboot the access point named AP-Office-1."

• "Power-cycle PoE port 3 on the switch named SW-Office."

Destructive examples respect UNIFI_CONFIRM_WRITES (default true): the model first gets a preview and has to call again with confirm: "YES" to apply.

Limitations

• Cloud-only. All requests go through the UniFi cloud endpoint (api.ui.com) via the Site Manager API and the Network Cloud Connector proxy. There is no direct-to-controller / local-network mode.

• Single account, owned consoles. Discovery resolves consoles your API key owns. Multi-console and multi-site accounts must pin IDs via the UNIFI_*_ID variables (see Troubleshooting).

• Auto-generated tools track the published docs. The unifi_gen_* tools are generated from UniFi's documented endpoints; their input schemas are only as accurate as the upstream documentation. Use unifi_raw_request if an endpoint behaves differently than its schema suggests.

• Network API requires recent firmware. The Network API is only available on consoles running firmware ≥ 5.0.3.

• No event streaming / websockets. Tools are request/response only; there is no live event subscription.

Troubleshooting

"Discovery: multiple consoles match …" Your Site Manager account has more than one UniFi console. Set UNIFI_CONSOLE_ID=<id> from one of the listed IDs. The same pattern applies to multi-Network-site (UNIFI_NETWORK_SITE_ID) and multi-Site-Manager-site (UNIFI_SITE_MANAGER_SITE_ID) cases.

401 Unauthorized The API key is missing the Network scope or has been revoked. Re-generate the key at unifi.ui.com with both Site Manager and UniFi Applications → Network scopes enabled. Rotate any key that has ever been exposed in a chat or commit.

Tools not showing in Claude Desktop Restart Claude Desktop after editing claude_desktop_config.json; config changes are only picked up on startup. The MCP log is at ~/Library/Logs/Claude/mcp-server-unifi.log (macOS); check it for startup errors or discovery failures.

Server stops right after a very large request The MCP SDK closes the stdio transport when one incoming message exceeds its line limit (see SECURITY.md); the process then exits without an error result. Split the input (for example fewer MACs or a smaller body per call) and restart the server.

Development

npm run dev                  # tsx watch
npm run test:unit            # unit tests (offline; what prebuild runs)
npm test                     # unit tests + the live smoke, which calls api.ui.com if UNIFI_API_KEY is set
npm run test:integration     # live read-only smoke only (needs UNIFI_API_KEY)
npm run codegen              # regenerate src/tools/generated/ from the live UniFi docs (see CONTRIBUTING.md first)
npm run inspector            # MCP Inspector
npm run build:mcpb           # build MCPB bundle + SBOMs into release/
npm run lint                 # ESLint
npm run typecheck            # tsc --noEmit

See CONTRIBUTING.md for the full workflow.

Architecture

Three-layer tool design. Hand-wrappers (unifi_sm_*, unifi_net_*) provide ergonomic, well-documented entry points for common operations with auto-resolved IDs and named arguments. The 80 auto-generated tools (unifi_gen_*) cover the endpoints listed in the codegen catalog (src/codegen/catalog.ts), with input schemas derived from the upstream UniFi docs. unifi_raw_request is the escape hatch for anything not covered by the first two layers.

Lazy ID discovery. On first use, the server calls GET /v1/hosts to find the owned console, then GET /v1/sites (Network and Site Manager) to discover both siteIds. Results are cached for the process lifetime. Concurrent callers share a single in-flight request via stored promises. All three IDs can be pinned via environment variables for multi-console / multi-site accounts.

Retries. A request is tried at most 3 times. 429 is retried on every method, honouring Retry-After (capped at 60 s), because the server rejected the request. 5xx and dropped connections are retried only for GET; a POST, PUT, PATCH or DELETE is resent after a network error only when the connection was never established (for example ECONNREFUSED, ENOTFOUND), so a write that may already have reached UniFi is never duplicated. Redirects are refused (the API key never leaves the configured host) and timeouts are not retried. Network failures are returned as an error with the cause and logged at warn.

Codegen pipeline. A separate build step (npm run codegen) fetches each documented endpoint page from developer.ui.com using the RSC: 1 header, runs a balanced-brace parser to extract the "endpoint":{...} block, converts the OpenAPI-style schema into a Zod expression, and emits one .ts file per endpoint. The output lives in src/tools/generated/ and is committed to git so builds work offline.

Security

• API key is read from UNIFI_API_KEY environment variable only. Never hardcoded.

• .env is gitignored.

• An MCP client config that holds the key in env (for example claude_desktop_config.json) stores it in plain text; keep that file private.

• The stderr logger redacts known secret patterns (UNIFI_API_KEY=..., X-API-Key, Authorization, apiKey, api_key, and api_key / apikey / token / access_token query parameters) and, by exact value, the configured API key wherever it appears. Output written by other tooling is not covered.

• Request paths are relative to the configured UNIFI_API_BASE origin, which must be https:// (plain http:// only for loopback test stubs); the API key is sent only to that origin and redirects are refused.

• Error texts from the UniFi API are scrubbed like log lines and cut to a fixed length before they reach the model.

• Keep UNIFI_CONFIRM_WRITES=true (the default) for a confirmation step on destructive operations.

• Tool results carry strings controlled by whoever can name things in your UniFi setup (device names, client hostnames, SSIDs, rule descriptions). The server instructions tell the model to treat them as data; your MCP client should still ask you before destructive tools run. The threat model is in SECURITY.md.

To report a vulnerability, please use GitHub Security Advisories; do not open a public issue. See SECURITY.md.

Maintenance status

• Maintained on a best-effort basis by one maintainer (@mguttmann) in spare time. There is no support contract and no guaranteed response time.

• Security fixes take priority over features. Report vulnerabilities privately (see Security).

• Dependency updates come from Dependabot; CI fails when a runtime dependency has a known high or critical advisory.

• Only the latest minor release gets fixes.

• The unifi_gen_* tools follow the published UniFi API documentation; when Ubiquiti changes the API, they are regenerated in a later release. Open items are listed in BACKLOG.md.

• Issues and pull requests are welcome; see CONTRIBUTING.md and the Code of Conduct.

Contributing

See CONTRIBUTING.md.

License

MIT, see LICENSE. Test fixtures excerpted from Ubiquiti's developer documentation are not covered by the MIT License; see NOTICE.