# 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