unifi-mcp-server

# unifi-mcp-server > Skill by [ara.so](https://ara.so) — MCP Skills collection. A Model Context Protocol (MCP) server exposing the UniFi Network Controller API. Provides 74+ tools for managing UniFi devices, clients, networks, WiFi, firewall rules, QoS, backups, port profiles, RADIUS, guest portals, and multi-site orchestration. ## What It Does - **Device Management**: List, monitor, restart, locate, upgrade UniFi devices (APs, switches, gateways) - **Network Configuration**: Create/update/delete networks, VLANs, subnets with DHCP - **Client Management**: Query, block, unblock, reconnect clients with analytics - **WiFi/SSID Management**: Create wireless networks with WPA2/WPA3, guest networks, VLAN isolation - **Firewall Rules**: Create/manage firewall rules, port forwarding, traffic filtering - **QoS Management**: Traffic prioritization, bandwidth control, traffic shaping - **Backup & Restore**: Automated scheduling, verification, download/upload - **Port Profiles**: Switch port configuration with PoE, VLAN trunking, 802.1X - **RADIUS & Guest Portal**: 802.1X authentication, hotspot packages - **Multi-Site**: Cross-site aggregation, analytics, site provisioning - **Network Topology**: Complete topology mapping and visualization ## Installation ### Via pip (Recommended) ```bash pip install unifi-mcp-server ``` ### Via uv ```bash uv pip install unifi-mcp-server ``` ### From source ```bash git clone https://github.com/enuno/unifi-mcp-server.git cd unifi-mcp-server pip install -e . ``` ## API Modes Three distinct API modes with different capabilities: ### Local Gateway API (Recommended) ✅ Full feature support with real-time data and configuration changes. **Required Environment Variables:** ```bash export UNIFI_API_TYPE=local export UNIFI_LOCAL_HOST=192.168.2.1 # Your gateway IP export UNIFI_USERNAME=admin export UNIFI_PASSWORD=your_password export UNIFI_SITE=default ``` ### Cloud Early Access API ⚠️ Site-centric access with limited read-only capabilities. **Required Environment Variables:** ```bash export UNIFI_API_TYPE=cloud-ea export UNIFI_API_KEY=your_cloud_api_key export UNIFI_SITE_MANAGER_ENABLED=true # Optional: multi-site aggregation ``` ### Cloud V1 API ⚠️ Limited to aggregate statistics only. **Required Environment Variables:** ```bash export UNIFI_API_TYPE=cloud-v1 export UNIFI_API_KEY=your_cloud_api_key ``` ## Transport Modes ### STDIO (Default) For local AI clients (Claude Desktop, Cursor): ```bash export MCP_SERVER_TRANSPORT=stdio unifi-mcp-server ``` ### SSE (Server-Sent Events) For network access and MCP gateways: ```bash export MCP_SERVER_TRANSPORT=sse export MCP_SERVER_PORT=3000 unifi-mcp-server ``` ### HTTP / Streamable HTTP ```bash export MCP_SERVER_TRANSPORT=http # or streamable_http export MCP_SERVER_PORT=3000 unifi-mcp-server ``` ## Configuration ### Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "unifi": { "command": "unifi-mcp-server", "env": { "UNIFI_API_TYPE": "local", "UNIFI_LOCAL_HOST": "192.168.2.1", "UNIFI_USERNAME": "admin", "UNIFI_PASSWORD": "your_password", "UNIFI_SITE": "default", "MCP_SERVER_TRANSPORT": "stdio" } } } } ``` ### MCP Gateway (SSE Mode) ```json { "mcpServers": { "unifi": { "url": "http://your-server-ip:3000/sse" } } } ``` ### Docker Compose ```yaml services: unifi-mcp: image: ghcr.io/enuno/unifi-mcp-server:latest environment: UNIFI_API_TYPE: local UNIFI_LOCAL_HOST: 192.168.2.1 UNIFI_USERNAME: admin UNIFI_PASSWORD: ${UNIFI_PASSWORD} UNIFI_SITE: default MCP_SERVER_TRANSPORT: sse MCP_SERVER_PORT: 3000 ports: - "3000:3000" ``` ## Core MCP Tools ### Device Management ```python # List all devices devices = await call_tool("list_devices") # Get device details device = await call_tool("get_device", {"device_id": "abc123"}) # Restart device result = await call_tool("restart_device", {"device_id": "abc123"}) # Locate device (blink LEDs) await call_tool("locate_device", { "device_id": "abc123", "enabled": True }) # Upgrade device firmware await call_tool("upgrade_device", {"device_id": "abc123"}) # Force provision device await call_tool("force_provision_device", {"device_id": "abc123"}) ``` ### Client Management ```python # List all clients clients = await call_tool("list_clients") # Get client details client = await call_tool("get_client", {"client_id": "aa:bb:cc:dd:ee:ff"}) # Block client await call_tool("block_client", { "client_id": "aa:bb:cc:dd:ee:ff", "blocked": True }) # Reconnect client await call_tool("reconnect_client", {"client_id": "aa:bb:cc:dd:ee:ff"}) # Get client statistics stats = await call_tool("get_client_stats", {"client_id": "aa:bb:cc:dd:ee:ff"}) ``` ### Network Configuration ```python # Create network network = await call_tool("create_network", { "name": "IoT Network", "vlan_id": 20, "subnet": "192.168.20.0/24", "dhcp_enabled": True, "dhcp_start": "192.168.20.10", "dhcp_stop": "192.168.20.250", "gateway": "192.168.20.1" }) # Update network await call_tool("update_network", { "network_id": "abc123", "name": "IoT Network Updated", "dhcp_dns": ["8.8.8.8", "8.8.4.4"] }) # Delete network await call_tool("delete_network", {"network_id": "abc123"}) # List networks networks = await call_tool("list_networks") ``` ### WiFi/SSID Management ```python # Create SSID ssid = await call_tool("create_ssid", { "name": "Guest WiFi", "password": "SecurePass123!", "security": "wpapsk", "vlan_id": 30, "guest_network": True, "hide_ssid": False }) # Update SSID await call_tool("update_ssid", { "ssid_id": "abc123", "name": "Guest WiFi Updated", "enabled": True }) # Delete SSID await call_tool("delete_ssid", {"ssid_id": "abc123"}) # List SSIDs ssids = await call_tool("list_ssids") ``` ### Firewall Rules ```python # Create firewall rule rule = await call_tool("create_firewall_rule", { "name": "Block IoT to LAN", "action": "drop", "rule_index": 2000, "protocol": "all", "src_network_id": "iot_network_id", "dst_network_id": "lan_network_id", "enabled": True }) # Update firewall rule await call_tool("update_firewall_rule", { "rule_id": "abc123", "enabled": False }) # Delete firewall rule await call_tool("delete_firewall_rule", {"rule_id": "abc123"}) # List firewall rules rules = await call_tool("list_firewall_rules") ``` ### Port Forwarding ```python # Create port forward forward = await call_tool("create_port_forward", { "name": "Web Server", "enabled": True, "protocol": "tcp", "src_port": "80", "dst_ip": "192.168.1.100", "dst_port": "8080", "log": True }) # Update port forward await call_tool("update_port_forward", { "forward_id": "abc123", "enabled": False }) # Delete port forward await call_tool("delete_port_forward", {"forward_id": "abc123"}) ``` ### QoS Management ```python # Create QoS rule qos = await call_tool("create_qos_rule", { "name": "Video Conference Priority", "enabled": True, "priority": "high", "bandwidth_limit": 10000, "protocol": "tcp", "dst_port": "443" }) # Update QoS rule await call_tool("update_qos_rule", { "rule_id": "abc123", "priority": "medium" }) # Delete QoS rule await call_tool("delete_qos_rule", {"rule_id": "abc123"}) # List QoS rules rules = await call_tool("list_qos_rules") ``` ### Port Profile Management ```python # Create port profile profile = await call_tool("create_port_profile", { "name": "VoIP Phones", "poe_mode": "auto", "vlan_id": 40, "native_network_id": "voice_network_id", "dot1x_ctrl": "auto", "lldpmed_enabled": True, "lldpmed_notify_enabled": True }) # Update port profile await call_tool("update_port_profile", { "profile_id": "abc123", "poe_mode": "pasv24" }) # Delete port profile await call_tool("delete_port_profile", {"profile_id": "abc123"}) # List port profiles profiles = await call_tool("list_port_profiles") ``` ### Device Port Overrides ```python # Override device port override = await call_tool("override_device_port", { "device_id": "switch123", "port_idx": 5, "port_profile_id": "voip_profile_id", "poe_mode": "auto", "name": "Conference Room Phone" }) # Remove port override await call_tool("remove_device_port_override", { "device_id": "switch123", "port_idx": 5 }) # Get device port configuration config = await call_tool("get_device_port_config", { "device_id": "switch123", "port_idx": 5 }) ``` ### Backup & Restore ```python # Create backup backup = await call_tool("create_backup", { "name": "weekly-backup", "include_settings": True }) # List backups backups = await call_tool("list_backups") # Download backup content = await call_tool("download_backup", {"backup_id": "abc123"}) # Restore from backup await call_tool("restore_backup", {"backup_id": "abc123"}) # Schedule backup