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 and httpx. 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)

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

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

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:

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:

{
  "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):

{
  "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