UniFi MCP Server Skill
Interact with UniFi Network, Protect and the UniFi cloud APIs using 343 MCP tools (local mode) 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_PROFILE=network unifi-mcp-server # clients, VLANs, WiFi, DHCP, DNS
UNIFI_PROFILE=devices unifi-mcp-server # device management and control
UNIFI_PROFILE=security unifi-mcp-server # firewall, VPN, ACLs, content filtering
UNIFI_PROFILE=system unifi-mcp-server # backups, QoS, traffic flows, sites
UNIFI_PROFILE=protect unifi-mcp-server # cameras, NVRs, sensors, alarms
Capability Domains
Network Operations (skills/unifi-network/)
Clients · VLANs · WiFi (SSIDs) · DHCP reservations · DNS · WAN · Vouchers
Device Management (skills/unifi-devices/)
Inventory · Adoption · Restarts/upgrades · Radio config · Port profiles · Switching/stacks · Topology · Diagnostics
Security (skills/unifi-security/)
Firewall rules · Firewall groups · Zone-based firewall (ZBF) · ACLs · Port forwarding · VPN · Site-to-site VPN · Content filtering
System & Monitoring (skills/unifi-system/)
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-ea |
UNIFI_LOCAL_HOST |
Gateway IP (local mode only) | — |
UNIFI_DEFAULT_SITE |
Default site ID | default |
UNIFI_LOCAL_VERIFY_SSL |
Verify the console's TLS certificate (local mode) | true |
API Mode Feature Matrix
| Feature | local | cloud-v1 | cloud-ea |
|---|---|---|---|
| Zone-based firewall | ✅ | ❌ | ❌ |
| Traffic flows | ✅ | ❌ | ❌ |
| Firewall rules/zones | ✅ | ❌ | ❌ |
| ACLs | ✅ | ❌ | ❌ |
| Traffic matching lists | ✅ | ❌ | ❌ |
| Device and client management | ✅ | ❌ | ❌ |
| Protect | ✅ | ❌ | ❌ |
| Sites and aggregate statistics | ✅ | ✅ | ✅ |
Site Manager, Mobility, InnerSpace, Carrier (needs UNIFI_SITE_MANAGER_ENABLED=true) |
✅ | ✅ | ✅ |
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