unifi-mcp

MCP server that turns Claude into a UniFi network specialist. Manage devices, optimize WiFi, audit security, and troubleshoot your network through natural language.

Quick Start

1. Get your API key from your UniFi controller: Settings > Integrations > Create API Key

2. Add to Claude Code:

claude mcp add unifi -e UNIFI_API_URL=https://YOUR-CONTROLLER-IP -e UNIFI_API_KEY=YOUR-KEY -- npx pproenca/unifi-mcp

3. Ask Claude anything about your network:

> What's the health of my network?
> Run a security audit
> Optimize my WiFi
> Show me all connected clients
> Set up a guest network with 24h vouchers

That's it. No config files, no cloning, no build step.

What It Does

Claude gets 31 tools (29 direct tools + 2 agent-routing tools) that cover the full UniFi Network API, plus specialist prompts that guide it to think like a network engineer:

| Ask | What happens | | ------------------------ | ------------------------------------------------------------------------- | | "Is my network healthy?" | Checks all devices, stats, firmware, client distribution, WAN status | | "Why is my WiFi slow?" | Correlates AP radio stats, TX retries, channel congestion, client counts | | "Is my network secure?" | Audits VLANs, firewall zones/policies, WiFi security types, DNS filtering | | "Optimize my WiFi" | Analyzes channels, power, data rates, band steering, SSID count | | "Create a guest network" | Orchestrates network + SSID + firewall rules + vouchers |

The specialist knowledge is in the tool descriptions and server instructions -- Claude knows what to check, what "good" looks like, and what to recommend.

Tools

Read (safe, no confirmation needed)

| Tool | What it reads | | ------------------------ | ----------------------------------------------- | | get_system_info | Controller version | | list_sites | All managed sites | | list_devices | Devices with state, firmware, model | | get_device | Single device: radios, ports, topology | | get_device_stats | Real-time CPU, memory, load, TX/RX, radio stats | | list_pending_devices | Devices awaiting adoption | | list_clients | Connected clients with type, AP, IP | | get_client | Single client detail | | list_networks | VLANs and network configs | | list_wifi | SSIDs with security, rates, isolation | | list_firewall_zones | Firewall zone definitions | | list_firewall_policies | Policies with ordering | | get_wan_status | WAN interface status | | list_vpn | VPN tunnels and servers | | list_dpi_apps | DPI application categories |

Write (Claude will ask for confirmation)

| Tool | What it does | | ------------------------ | -------------------------------------------------------------- | | device_action | Restart, upgrade, locate, adopt | | client_action | Authorize, block, reconnect | | manage_network | Create/update/delete VLANs | | manage_wifi | Create/update/delete SSIDs | | manage_firewall_zone | Create/update/delete zones | | manage_firewall_policy | Create/update/delete/reorder policies | | manage_acl_rule | Create/update/delete/reorder ACL rules | | manage_dns_policy | Create/update/delete DNS policies | | manage_traffic_rule | Create/update/delete traffic rules | | manage_vouchers | Create/delete hotspot vouchers | | save_network_profile | Save personalized network profile to ~/.unifi-mcp/profile.json |

Agent Routing

| Tool | What it does | | ---------------- | ----------------------------------------------------------------------------- | | search_actions | Search an action catalog by query/category/read-only to find the right action | | execute_action | Execute any catalog action by actionId with a generic params object |

Prompts

| Prompt | What it does | | --------------------- | ---------------------------------------------------------------------------------------------- | | init | First-time setup: discover your network, agree on conventions, assess security, save a profile | | doctor | Diagnose issues: check devices, clients, connectivity, and performance | | optimize | Full optimization: WiFi, client placement, firewall hygiene, device health, architecture | | security-review | Threat model: attack chains, systemic findings, reachability tracing, live remediation |

Environment Variables

| Variable | Required | Description | | ------------------ | -------- | --------------------------------------------------------------------- | | UNIFI_API_URL | Yes | Controller URL, e.g. https://192.168.1.1 | | UNIFI_API_KEY | Yes | API key from Settings > Integrations | | UNIFI_SITE_ID | No | Site ID (auto-detects first site) | | UNIFI_VERIFY_TLS | No | Set to true to enforce TLS (default: false for self-signed certs) |

Requirements

• UniFi controller with API access (Network 10.x+)
• Node.js >= 18
• An API key (generated in your controller's Integrations settings)

Your controller also has built-in API docs at https://YOUR-CONTROLLER-IP/unifi-api/network — useful for exploring endpoints and schemas.

Development

git clone https://github.com/pproenca/unifi-mcp.git
cd unifi-mcp
npm install
npm run generate:openapi-types
npm run build
npm test
npm run test:coverage
npm run test:mcp-smoke
npm run verify

# Test with MCP Inspector
mise run dev

# Or run directly
UNIFI_API_URL=https://192.168.1.1 UNIFI_API_KEY=xxx node dist/index.js

npm run build emits the publishable server into dist/. Test runs compile into dist-test/ so the npm package only ships runtime assets.

License

MIT