unifi-mcp

UniFi MCP

FastMCP server for local UniFi controller management. Exposes a single unifi action router and a unifi_help reference tool covering devices, clients, network configuration, and controller monitoring.

Overview

The server connects to a self-hosted UniFi controller (including UDM Pro) and proxies all operations through a single MCP tool. A unified action parameter replaces 31 individual tools while preserving every capability. Destructive operations require explicit confirmation. Bearer token auth protects the HTTP endpoint in production.

What this repository ships

• unifi_mcp/: server, client, config, formatters, models, services, resources, and tools
• skills/unifi/: client-facing skill
• docs/: API notes, action-pattern rationale, testing notes
• .claude-plugin/, .codex-plugin/, gemini-extension.json: client manifests
• docker-compose.yaml, Dockerfile: container deployment
• tests/: unit, resource, and integration tests

Tools

unifi

Single action router for all UniFi operations.

Parameters

Parameter	Type	Required	Default	Description
action	string	yes	—	Action to perform (see below)
site_name	string	no	"default"	UniFi site name. Ignored by get_sites, get_controller_status, get_user_info
mac	string	no	null	Device or client MAC address (any format: aa:bb:cc, AA-BB-CC, aabb.cc)
limit	int	no	varies	Maximum results to return
connected_only	bool	no	true	get_clients: return only currently connected clients
active_only	bool	no	true	get_alarms: return only unarchived alarms
by_filter	string	no	"by_app"	get_dpi_stats: "by_app" or "by_cat"
name	string	no	null	set_client_name: new display name (empty string removes it)
note	string	no	null	set_client_note: note text (empty string removes it)
minutes	int	no	480	authorize_guest: access duration in minutes
up_bandwidth	int	no	null	authorize_guest: upload limit in Kbps
down_bandwidth	int	no	null	authorize_guest: download limit in Kbps
quota	int	no	null	authorize_guest: data quota in MB
confirm	bool	no	null	Set to true to confirm destructive operations

unifi_help

Returns full markdown reference for all actions and parameters. No parameters needed.

---

Action Groups

Device Management

Action	MAC Required	Description
get_devices	no	List all devices on a site with status, model, IP, and uptime
get_device_by_mac	yes	Get full details for one device by MAC
restart_device	yes	Destructive — reboot the device
locate_device	yes	Activate the locate LED on the device

get_devices response fields per device: name, model, type (Access Point / Gateway / Switch), status (Online / Offline), ip, mac, uptime, version

restart_device example:

unifi action=restart_device mac=aa:bb:cc:dd:ee:ff confirm=true

---

Client Management

Action	MAC Required	Description
get_clients	no	List clients. connected_only=true (default) filters offline entries
reconnect_client	yes	Destructive — force a client to reconnect (kick-sta)
block_client	yes	Destructive — block a client from network access
unblock_client	yes	Re-allow a previously blocked client
forget_client	yes	Destructive — remove all historical data for a client (GDPR)
set_client_name	yes	Set or update the display alias for a client
set_client_note	yes	Set or update the note for a client

set_client_name / set_client_note: Both resolve the client by MAC against the controller user list (/list/user), then POST to /upd/user/{id}. Pass an empty string (name="") to remove the value.

Workflow — block a client:

# Step 1: find the MAC
unifi action=get_clients connected_only=true

# Step 2: block it
unifi action=block_client mac=aa:bb:cc:dd:ee:ff confirm=true

# Step 3: verify
unifi action=get_clients connected_only=false

---

Network Configuration