unifi

UniFi MCP Server Skill

Interact with your UniFi Network Controller using 86+ MCP tools across six capability domains. The server supports three API modes (local gateway, cloud-v1, cloud-ea) and requires UniFi Network 9.0+ for zone-based firewall features.

Quick Setup

Via MCP (recommended for full tool access)

Add to your MCP client config (~/.claude/mcp.json or equivalent):

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

Via CLI (scoped invocation without loading all tools into context)

# Install
pip install unifi-mcp-server
# or: uvx unifi-mcp-server --help

# Set credentials once
export UNIFI_API_KEY=your-api-key
export UNIFI_API_TYPE=local
export UNIFI_LOCAL_HOST=192.168.2.1

# Run any tool directly
unifi-cli list-clients --site default
unifi-cli get-device-details --site default --device-id <id>

Scoped MCP profiles (reduce context footprint)

Start the server with only the tools you need:

unifi-mcp-server --profile network    # clients, VLANs, WiFi, DHCP, DNS
unifi-mcp-server --profile devices    # device management and control
unifi-mcp-server --profile security   # firewall, VPN, ACLs, content filtering
unifi-mcp-server --profile system     # backups, QoS, traffic flows, sites

---

Capability Domains

Network Operations (skills/unifi-network.md)

Clients · VLANs · WiFi (SSIDs) · DHCP reservations · DNS · WAN · Vouchers

Device Management (skills/unifi-devices.md)

Inventory · Adoption · Restarts/upgrades · Radio config · Port profiles · Switching/stacks · Topology · Diagnostics

Security (skills/unifi-security.md)

Firewall rules · Firewall groups · Zone-based firewall (ZBF) · ACLs · Port forwarding · VPN · Site-to-site VPN · Content filtering

System & Monitoring (skills/unifi-system.md)

Sites · Multi-site aggregation · Backups · QoS / traffic routes · Traffic flow analytics · DPI · RADIUS · Guest portal · Hotspot packages

---

Environment Variables

Variable	Description	Default
UNIFI_API_KEY	API key from UniFi controller or unifi.ui.com	required
UNIFI_API_TYPE	local, cloud-v1, or cloud-ea	cloud-v1
UNIFI_LOCAL_HOST	Gateway IP (local mode only)	—
UNIFI_SITE	Default site ID	default
UNIFI_VERIFY_SSL	Verify TLS certificates	true

API Mode Feature Matrix

Feature	local	cloud-v1	cloud-ea
Zone-based firewall	✅	❌	❌
Traffic flows	✅	❌	❌
Firewall rules/zones	✅	❌	❌
ACLs	❌	✅	✅
Traffic matching lists	❌	✅	✅
Site aggregation	✅	✅	✅
Device management	✅	✅	✅

Usage Examples

# Check what clients are online on the main site
List all active clients on site "default"

# Investigate a device
Get details for the device with MAC aa:bb:cc:dd:ee:ff

# Firewall audit
List all firewall policies in zone-based firewall

# Bandwidth troubleshooting
Show top traffic flows for the last hour

# Backup before a change
Trigger a backup on site "default", then update the guest SSID password