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.

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 ergonomic hand-wrappers + 80 auto-generated tools for complete coverage + 1 raw-request escape hatch (86 + 80 + 1 = 167).
3 MCP resources and 3 MCP prompts for ready-made workflows.
Lazy ID discovery (consoleId / Network siteId / Site Manager siteId), cached for the process lifetime.
Optional write guard — UNIFI_CONFIRM_WRITES turns destructive tools into preview-then-confirm.
Secret redaction in all stderr log output.

Requirements

Node.js ≥ 20.
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 source

git clone https://github.com/mguttmann/the-real-unifi-mcp.git
cd the-real-unifi-mcp
npm install
cp .env.example .env
# Edit .env: set UNIFI_API_KEY (Site Manager key with Network scope)
npm run build
npm start

As MCPB bundle

npm run build:mcpb
# Resulting `the-real-unifi-mcp-<version>.mcpb` can be installed directly in Claude Desktop.

Configuration

Variable	Default	Description
`UNIFI_API_KEY`	(required)	Site Manager API key with Network scope
`UNIFI_API_BASE`	`https://api.ui.com`	API base URL
`UNIFI_CONFIRM_WRITES`	`false`	If true, destructive tools require `confirm: "YES"`
`UNIFI_TIMEOUT_MS`	`30000`	Per-request timeout (ms)
`UNIFI_LOG_LEVEL`	`info`	`debug` \| `info` \| `warn` \| `error`
`UNIFI_CONSOLE_ID`	—	Override discovery (pin to a specific console)
`UNIFI_NETWORK_SITE_ID`	—	Override discovery (pin to a specific Network site)
`UNIFI_SITE_MANAGER_SITE_ID`	—	Override discovery (pin to a specific Site Manager site)

Claude Desktop config

Add to claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "unifi": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/the-real-unifi-mcp/.env",
        "/absolute/path/to/the-real-unifi-mcp/dist/index.js"
      ]
    }
  }
}

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

Claude Code config

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "unifi": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/the-real-unifi-mcp/.env",
        "/absolute/path/to/the-real-unifi-mcp/dist/index.js"
      ]
    }
  }
}

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
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}. 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, destructive tools execute directly. Set UNIFI_CONFIRM_WRITES=true to require an explicit confirm: "YES" argument; otherwise destructive calls return a redacted preview:

{
  "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": "UNIFI_CONFIRM_WRITES=true is set. Re-run with confirm: \"YES\" to apply this change."
  }
}

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."
"Block the client with MAC aa:bb:cc:dd:ee:ff until I unblock it."

Destructive examples respect UNIFI_CONFIRM_WRITES — when set, the model will first ask for confirmation before applying.

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 80 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.

Development

npm run dev                  # tsx watch
npm test                     # unit tests
npm run test:integration     # live read-only smoke (needs UNIFI_API_KEY)
npm run codegen              # regenerate src/tools/generated/ from UniFi docs
npm run inspector            # MCP Inspector
npm run build:mcpb           # build MCPB bundle artifact
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_*) guarantee complete coverage of every documented endpoint, 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.

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 production builds work offline.

Security

API key is read from UNIFI_API_KEY environment variable only. Never hardcoded.
.env is gitignored.
The stderr logger redacts five known secret patterns (UNIFI_API_KEY=…, X-API-Key, Authorization, apiKey, api_key).
Set UNIFI_CONFIRM_WRITES=true for an extra confirmation step on destructive operations.

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

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github		.github
mcpb		mcpb
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

the-real-unifi-mcp

Features

Requirements

Installation

From source

As MCPB bundle

Configuration

Claude Desktop config

Claude Code config

Tool reference

Site Manager hand-wrappers (10)

Network hand-wrappers (76)

Auto-generated tools (80)

Escape hatch (1)

Resources

Prompts

Write safety

Examples

Limitations

Troubleshooting

Development

Architecture

Security

Contributing

License

About

Uh oh!

Releases 3

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

the-real-unifi-mcp

Features

Requirements

Installation

From source

As MCPB bundle

Configuration

Claude Desktop config

Claude Code config

Tool reference

Site Manager hand-wrappers (10)

Network hand-wrappers (76)

Auto-generated tools (80)

Escape hatch (1)

Resources

Prompts

Write safety

Examples

Limitations

Troubleshooting

Development

Architecture

Security

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages