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

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