# UniFi Internal API MCP Server

An MCP (Model Context Protocol) server that exposes the **internal** UniFi Controller API — the same API the web UI uses — as tools for AI assistants.

This wraps the cookie-authenticated controller endpoints documented in the [Art-of-WiFi/UniFi-API-client](https://github.com/Art-of-WiFi/UniFi-API-client) PHP library, providing ~170 tools for managing UniFi networks.

## Features

- **Full controller access**: Clients, devices, WLANs, networks, firewall, statistics, events, admins, firmware, backups, DNS, RADIUS, DPI, hotspot/vouchers, and more
- **Cookie-based authentication**: Uses the same session auth as the UniFi web UI
- **UniFi OS support**: Works with UDM, UDR, UCG, and legacy standalone controllers
- **Readonly safety mode**: Write operations blocked by default — enable explicitly
- **170+ tools** across 19 categories

## Quick Start

1. Clone this repository
2. Copy `.env.example` to `.env` and fill in your controller details
3. Run: `uv run unifi-internal-api-mcp`

## Configuration

| Variable | Description | Default |
|---|---|---|
| `UNIFI_HOST` | Controller URL (e.g. `https://192.168.1.1`) | *required* |
| `UNIFI_USERNAME` | Controller username | |
| `UNIFI_PASSWORD` | Controller password | |
| `UNIFI_TOKEN` | Pre-authenticated TOKEN cookie (alternative to username/password) | |
| `UNIFI_SITE` | Site name | `default` |
| `UNIFI_IS_UNIFI_OS` | UniFi OS controller (UDM/UDR/UCG) | `true` |
| `UNIFI_READONLY` | Block all write operations | `true` |
| `UNIFI_SSL_VERIFY` | Verify SSL certificates | `false` |

### Authentication

**Option 1: Username/password** — for self-hosted controllers without 2FA:
```
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your-password
```

**Option 2: Browser token** — for cloud-hosted (ui.com) or 2FA-enabled controllers:
1. Log into your controller in a browser
2. Open DevTools (Cmd+Option+I) > **Application** > **Cookies**
3. Copy the `TOKEN` cookie value
```
UNIFI_TOKEN=eyJhbGciOiJIUzI1NiIs...
```
The token expires after ~30 days. When using a token, the server won't log out (so your browser session stays valid).

## Tool Categories

| Module | Tools | Description |
|---|---|---|
| `system` | 15 | Sysinfo, health, dashboard, settings, device states |
| `sites` | 13 | Site management, settings (country, SNMP, NTP, etc.) |
| `clients` | 20 | Client management, guest auth, block/unblock |
| `devices` | 23 | Device adoption, restart, locate, radio settings |
| `hotspot` | 9 | Vouchers, hotspot operators, guest login |
| `wlans` | 8 | WLAN configuration, MAC filters |
| `networks` | 4 | Network CRUD |
| `firewall` | 5 | Firewall groups and rules |
| `statistics` | 22 | 5min/hourly/daily/monthly stats, speedtest, IPS |
| `events` | 4 | Events and alarms |
| `admins` | 8 | Admin management and permissions |
| `firmware` | 10 | Firmware updates, rolling upgrades |
| `backups` | 3 | Backup generation and export |
| `dns` | 3 | DNS records (v2 API) |
| `radius` | 5 | RADIUS profiles and accounts |
| `tags` | 5 | Device tags |
| `dpi` | 5 | DPI stats, port forwarding, system log |
| `user_groups` | 4 | User groups (bandwidth profiles) |
| `ap_groups` | 4 | AP groups (v2 API) |

## MCP Client Configuration

Add to your MCP client config (e.g. Claude Desktop):

```json
{
  "mcpServers": {
    "unifi-internal": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unifi_internal_api_mcp", "unifi-internal-api-mcp"],
      "env": {
        "UNIFI_HOST": "https://your-controller-url",
        "UNIFI_TOKEN": "eyJhbGciOiJIUzI1NiIs...",
        "UNIFI_SITE": "default",
        "UNIFI_READONLY": "true"
      }
    }
  }
}
```