# 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:**
```bash
claude mcp add unifi -e UNIFI_API_URL=https://YOUR-CONTROLLER-IP -e UNIFI_API_KEY=YOUR-KEY -- npx 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
```bash
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