# Unifi AP MCP

MCP (Model Context Protocol) server for UniFi Network Controller — full API coverage for managing APs, clients, WLANs, firewall rules, VLANs, port forwards, and more.

Built with [FastMCP](https://github.com/jlowin/fastmcp) and [httpx](https://www.python-httpx.org/). Supports both the UniFi Integration API v1 and the Legacy API.

## Features

- **Devices** — list, get stats (channel, power, uptime, memory, tx/rx)
- **Clients** — connected clients, all-time history, block/unblock/kick, guest auth
- **WLANs** — list, create, update (password, band, VLAN, guest mode), delete
- **Networks (VLANs)** — list, create, update, delete
- **Firewall** — rules (create/update/delete) + groups (address-group/port-group)
- **Port Forwards** — list, create, update, delete
- **Static Routes** — list
- **DPI Stats** — per-client and site-level deep packet inspection
- **Traffic Reports** — hourly/daily per site, AP, or user
- **Health & Sysinfo** — subsystem status, controller version
- **Rogue APs** — neighboring AP scan results
- **Vouchers** — hotspot voucher list
- **Settings** — all site settings
- **RADIUS Profiles** — list

## Requirements

- Python 3.11+
- UniFi Network Application 8.x+ (self-hosted or UniFi Cloud Gateway)
- API Key: **Settings → Control Plane → Integrations → Create API Key**

## Installation

### Option 1: Run directly with `uv` (recommended)

```bash
pip install uv  # if not already installed

UNIFI_HOST=192.168.1.1 UNIFI_PORT=11443 UNIFI_API_KEY=your-api-key \
  uvx --from git+https://github.com/haiduongacm/unifi-ap-mcp server.py
```

### Option 2: Clone and run

```bash
git clone https://github.com/haiduongacm/unifi-ap-mcp.git
cd unifi-ap-mcp

uv venv && uv pip install -e .

UNIFI_HOST=192.168.1.1 \
UNIFI_PORT=11443 \
UNIFI_API_KEY=your-api-key \
  uv run server.py
```

### Option 3: Docker

```bash
docker build -t unifi-ap-mcp .

docker run -d \
  -p 8001:8000 \
  -e UNIFI_HOST=192.168.1.1 \
  -e UNIFI_PORT=11443 \
  -e UNIFI_API_KEY=your-api-key \
  unifi-ap-mcp
```

Or with `docker-compose`:

```yaml
services:
  unifi-network:
    build: .
    ports:
      - "8001:8000"
    environment:
      MCP_TRANSPORT: streamable-http
      UNIFI_HOST: 192.168.1.1
      UNIFI_PORT: "11443"
      UNIFI_API_KEY: ${UNIFI_API_KEY}
    restart: unless-stopped
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `UNIFI_HOST` | `127.0.0.1` | UniFi controller IP or hostname |
| `UNIFI_PORT` | `11443` | HTTPS port (11443 for self-hosted, 443 for cloud) |
| `UNIFI_API_KEY` | *(required)* | API key from Settings → Integrations |
| `MCP_TRANSPORT` | `stdio` | Transport: `stdio` \| `sse` \| `streamable-http` |
| `MCP_PORT` | `8000` | Port when using HTTP transport |

## MCP Client Configuration

### Claude Desktop / Claude Code (`mcp.json`)

**stdio mode:**
```json
{
  "mcpServers": {
    "unifi-network": {
      "command": "uv",
      "args": ["run", "/path/to/server.py"],
      "env": {
        "UNIFI_HOST": "192.168.1.1",
        "UNIFI_PORT": "11443",
        "UNIFI_API_KEY": "your-api-key"
      }
    }
  }
}
```

**HTTP mode (after `docker run` or `uv run` with `MCP_TRANSPORT=streamable-http`):**
```json
{
  "mcpServers": {
    "unifi-network": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

## Getting Your API Key

1. Log in to your UniFi Network Application
2. Go to **Settings → Control Plane → Integrations**
3. Click **Create API Key**
4. Copy the key — it is shown only once

> The API key replaces username/password authentication. No session management needed.

## Notes

- TLS verification is disabled (`verify=False`) to support self-signed certificates on self-hosted controllers. For production use behind a reverse proxy with a valid certificate, set `verify=True` in `server.py`.
- `site_id` defaults to `"default"` which resolves to your first site. Pass a site name or UUID for multi-site setups.

## License

MIT