unifi-mcp

MCP server that turns Claude into a UniFi network specialist. Manage devices, optimize WiFi, audit security, and troubleshoot your network through natural language.

Quick Start

1. Get your API key from your UniFi controller: Settings > Integrations > Create API Key

2. Add to Claude Code:

claude mcp add unifi -e UNIFI_API_URL=https://YOUR-CONTROLLER-IP -e UNIFI_API_KEY=YOUR-KEY -- npx unifi-mcp

3. Ask Claude anything about your network:

> What's the health of my network?
> Run a security audit
> Optimize my WiFi
> Show me all connected clients
> Set up a guest network with 24h vouchers

That's it. No config files, no cloning, no build step.

What It Does

Claude gets 31 tools (29 direct tools + 2 agent-routing tools) that cover the full UniFi Network API, plus specialist prompts that guide it to think like a network engineer:

Ask	What happens
"Is my network healthy?"	Checks all devices, stats, firmware, client distribution, WAN status
"Why is my WiFi slow?"	Correlates AP radio stats, TX retries, channel congestion, client counts
"Is my network secure?"	Audits VLANs, firewall zones/policies, WiFi security types, DNS filtering
"Optimize my WiFi"	Analyzes channels, power, data rates, band steering, SSID count
"Create a guest network"	Orchestrates network + SSID + firewall rules + vouchers

The specialist knowledge is in the tool descriptions and server instructions -- Claude knows what to check, what "good" looks like, and what to recommend.

Tools

Read (safe, no confirmation needed)

Tool	What it reads
get_system_info	Controller version
list_sites	All managed sites
list_devices	Devices with state, firmware, model
get_device	Single device: radios, ports, topology
get_device_stats	Real-time CPU, memory, load, TX/RX, radio stats
list_pending_devices	Devices awaiting adoption
list_clients	Connected clients with type, AP, IP
get_client	Single client detail
list_networks	VLANs and network configs
list_wifi	SSIDs with security, rates, isolation
list_firewall_zones	Firewall zone definitions
list_firewall_policies	Policies with ordering
get_wan_status	WAN interface status
list_vpn	VPN tunnels and servers
list_dpi_apps	DPI application categories

Write (Claude will ask for confirmation)

Tool	What it does
device_action	Restart, upgrade, locate, adopt
client_action	Authorize, block, reconnect
manage_network	Create/update/delete VLANs
manage_wifi	Create/update/delete SSIDs
manage_firewall_zone	Create/update/delete zones
manage_firewall_policy	Create/update/delete/reorder policies
manage_acl_rule	Create/update/delete/reorder ACL rules
manage_dns_policy	Create/update/delete DNS policies
manage_traffic_rule	Create/update/delete traffic rules
manage_vouchers	Create/delete hotspot vouchers
save_network_profile	Save personalized network profile to ~/.unifi-mcp/profile.json

Agent Routing

Tool	What it does
search_actions	Search an action catalog by query/category/read-only to find the right action
execute_action	Execute any catalog action by actionId with a generic params object

Prompts

Prompt	What it does
init	First-time setup: discover your network, agree on conventions, assess security, save a profile
doctor	Diagnose issues: check devices, clients, connectivity, and performance
optimize	Full optimization: WiFi, client placement, firewall hygiene, device health, architecture
security-review	Threat model: attack chains, systemic findings, reachability tracing, live remediation

Environment Variables

Variable	Required	Description
UNIFI_API_URL	Yes	Controller URL, e.g. https://192.168.1.1
UNIFI_API_KEY	Yes	API key from Settings > Integrations
UNIFI_SITE_ID	No	Site ID (auto-detects first site)
UNIFI_VERIFY_TLS	No	Set to true to enforce TLS (default: false for self-signed certs)

Requirements

• UniFi controller with API access (Network 10.x+)
• Node.js >= 18
• An API key (generated in your controller's Integrations settings)

Your controller also has built-in API docs at https://YOUR-CONTROLLER-IP/unifi-api/network — useful for exploring endpoints and schemas.

Development

git clone https://github.com/pproenca/unifi-mcp.git
cd unifi-mcp
npm install
npm run generate:openapi-types
npm run build
npm test
npm run test:coverage
npm run test:mcp-smoke
npm run verify

# Test with MCP Inspector
mise run dev

# Or run directly
UNIFI_API_URL=https://192.168.1.1 UNIFI_API_KEY=xxx node dist/index.js

npm run build emits the publishable server into dist/. Test runs compile into dist-test/ so the npm package only ships runtime assets.

License

MIT