Unifi MCP Server

UniFi MCP Server

AI-native control of UniFi networks through the Model Context Protocol

An MCP server that exposes UniFi Network, UniFi Protect and the UniFi cloud APIs (Site Manager, Mobility, InnerSpace, Carrier Fabric) as MCP tools, so AI agents can read and change UniFi infrastructure through one standard interface. It runs against one controller or, in fleet mode, many.

Current release: 0.8.0. See CHANGELOG.md for what changed.

Contents

• Features
• API modes
• Quick start
• Agent skills
• Tool profiles and safety controls
• Network transports and deployment
• Calling the server from code
• Native MCP prompts
• Documentation
• Development

Features

343 tools in local mode, from 60 modules.

• Network: clients (search, block, reconnect), networks and VLANs, WiFi SSIDs, DHCP reservations, DNS, WAN, guest vouchers, QoS profiles and traffic routes, DPI statistics, traffic flows.
• Devices: inventory, adoption, restart, locate, upgrade, radio settings, port profiles and per-port overrides, switching and stacks, topology export (JSON, GraphML, DOT), diagnostics, WiFi channel planning.
• Security: legacy firewall rules and groups, zone-based firewall (zones, policies, zone matrix), ACL rules, traffic matching lists, port forwarding, VPN and site-to-site VPN, content filtering, RADIUS and the guest portal.
• Protect: cameras, NVRs, views, events, sensors, lights, chimes, sirens, relays, speakers, alarm hubs and the alarm manager.
• Cloud: Site Manager (hosts, sites, cross-site statistics), the connector proxy, Mobility workspaces and devices, InnerSpace floor plans and inventory, Carrier Fabric subscribers and service plans.
• Operations: sites, backups (create, schedule, download, restore), events, multi-site aggregation, device migration between sites.
• Fleet mode (optional, with Postgres and Redis): many controllers behind one server, a controller registry with encrypted credentials, server-issued tokens with roles, a shared read cache, several replicas and background workers, and fleet_* tools that read across controllers. See MULTI_CONTROLLER.md and docs/FLEET_SCALING_PLAN.md.
• Native prompts: eight parameterised UniFi operational workflows (health check, client connectivity, WiFi performance, device investigation, firewall review, change planning, Protect health, fleet summary) exposed through the standard prompts/list and prompts/get operations. See docs/PROMPTS.md.
• Safety: every mutating tool needs confirm=True and supports dry_run=True, plus read-only and dry-run server modes, role-based access over risk tiers, and a hash-chained audit log (see below).
• A2A discovery and delegation: an agent card built from the live tool registry, served at /a2a/agent-card and /.well-known/agent-card.json, plus a capability manifest and a delegation endpoint that runs a registered tool under the server's own role, confirmation and audit controls. See A2A.md.
• Observability: Prometheus /metrics, /healthz, SIEM export of audit records, optional Redis caching, webhooks with HMAC verification.

API modes

Set UNIFI_API_TYPE to choose how the server reaches UniFi.

The cloud tools (Site Manager, Mobility, InnerSpace, Carrier Fabric) call api.ui.com and are registered in every mode. Set UNIFI_SITE_MANAGER_ENABLED=true to use them. In local mode the server registers 343 tools; in either cloud mode, 71.

Zone-based firewall tools need UniFi Network 9.0 or later. Some documented UniFi endpoints do not exist on every firmware version; see docs/UNIFI_API.md.

UniFi Network 11 / UniFi OS 6: compatible per released documentation, with four items pending live-controller verification — not yet a claim of full support. USG gateways and the classic, self-hosted Network Application Server are removed platform targets; fleet_health automatically flags any registered controller with a USG in its device inventory, but there is no API signal to auto-detect a classic Network Application Server, so label that controller instead (e.g. deployment=classic-server) and filter on it. Network 11 replaces the statistics engine and resets historical data, so the statistics tools (get_historical_stats, get_speed_test_history, get_dpi_statistics, list_top_applications, get_client_dpi) attach a statistics_note to every empty response — an empty history right after the upgrade is expected, not an outage. See docs/NETWORK_11_COMPATIBILITY.md for the full compatibility matrix.

Quick start

1. Get an API key

1. Sign in to UniFi Site Manager.
2. Go to Settings → Control Plane → Integrations and choose Create API Key.
3. Copy the key. It is shown only once.

2. Install

pip install unifi-mcp-server          # or: uv tool install unifi-mcp-server

Fleet mode extras (Postgres, Redis):

pip install 'unifi-mcp-server[fleet]'

Or use the container image (amd64, arm64 and arm/v7; the -fleet variant for amd64 and arm64):

docker pull ghcr.io/enuno/unifi-mcp-server:latest

3. Add it to your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows), Cursor (mcp.json, from View: Open MCP Settings) and most other MCP clients take the same mcpServers block:

{

"mcpServers": { "unifi": { "command": "uvx", "args": ["unifi-mcp-server"], "env": { "UNIFI_API_KEY": " ", "UNIFI_API_TYPE": "local", "UNIFI_LOCAL_HOST": "192.168.2.1" } } } }

If you installed with pip, use "command": "unifi-mcp-server" and drop args. To run the container instead:

{

"mcpServers": { "unifi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "UNIFI_API_KEY=your-api-key-here", "-e", "UNIFI_API_TYPE=local", "-e", "UNIFI_LOCAL_HOST=192.168.2.1", "ghcr.io/enuno/unifi-mcp-server:latest" ] } } }

Keep -i and do not add -d: the client talks to the server over the container's stdin and stdout.

4. Main settings

.env.example lists every setting with comments, including audit logging, SIEM export, metrics, Supermemory and agnost.ai.

Agent skills

The skills/ directory holds agent skills: Markdown files an AI agent loads on demand, so it knows which UniFi tools exist and how to use them safely without keeping every tool definition in context. Each skill is a folder with a SKILL.md, in the layout Claude Code and other agents install.

Using the server (operator skills)

Changing this codebase (developer skills)

Install

Claude Code loads skills from ~/.claude/skills/ /SKILL.md (every session) or /.claude/skills/ /SKILL.md (one project). Copy the folders you want:

git clone https://github.com/enuno/unifi