Best for
- Home or small-office users running a local UniFi gateway who want AI-assisted network operations
- Technically comfortable users familiar with UniFi controller concepts who will validate tool behavior incrementally
U
UniFi MCP Server
Community
MCP server for managing UniFi network devices, WiFi, and firewalls via the official UniFi API
GitHub source repository ↗
48FMRS · D
Broad feature coverage (devices, networks, WiFi, firewall, QoS, backups, topology), but the server.json manifest and the README's described latest version disagree on packaging, transport, and auth variables, and several enterprise security features remain planned rather than implemented — verify the docs for the specific version installed before relying on it.
UniFi MCP Server is a third-party community project (by enuno) that exposes the UniFi Network Controller's official API to AI agents via the Model Context Protocol. It can list and control devices (APs, switches, gateways), manage clients, create/modify WiFi networks and VLANs, configure firewall rules and Zone-Based Firewall (ZBF) policies, and manage QoS, backups, and multi-site setups. The repository contains two overlapping configuration stories: the published server.json manifest (npm package v0.2.0, stdio transport, authenticating with UNIFI_HOST/UNIFI_USERNAME/UNIFI_PASSWORD) and the README's description of the latest release (PyPI package v0.2.5, authenticating with UNIFI_API_KEY and UNIFI_API_TYPE, and supporting stdio/SSE/HTTP/Streamable HTTP transports). The README also states several 'Phase 5' capabilities (dry-run mode, audit logging, RBAC, A2A) are still planned, not yet implemented — check the docs for the version you actually install.
Tools
list_devices
Lists UniFi devices (access points, switches, gateways) and their status for a given site.
create_wlan
Creates a new WiFi/SSID network with configurable security, guest mode, and VLAN isolation.
list_top_applications
Returns top bandwidth-consuming applications based on Deep Packet Inspection (DPI) statistics.
create_firewall_zone
Creates a Zone-Based Firewall (ZBF) zone for network segmentation.
update_zbf_policy
Updates a zone-to-zone firewall policy (e.g., accept or reject traffic between two zones).
Setup
1) Determine which distribution you're actually installing: the repo's server.json manifest corresponds to an npm package (v0.2.0, stdio transport, requiring UNIFI_HOST/UNIFI_USERNAME/UNIFI_PASSWORD), while the README describes the latest stable release (v0.2.5) installed via pip install unifi-mcp-server with a different UNIFI_API_KEY/UNIFI_API_TYPE-based config — the two env-var schemes are not interchangeable, so confirm which one matches your install. 2) For the npm package, launch it in your MCP client with npx -y unifi-mcp-server and set UNIFI_HOST, UNIFI_USERNAME, UNIFI_PASSWORD (optionally UNIFI_PORT, UNIFI_VERIFY_SSL, UNIFI_SITE). 3) For the PyPI package, use the README's UNIFI_API_KEY/UNIFI_API_TYPE/UNIFI_LOCAL_HOST variables instead. 4) Restart your client and test with a read-only tool first before running any mutating operations.
claude_desktop_config.json
{"mcpServers":{"unifi":{"command":"npx","args":["-y","unifi-mcp-server"],"env":{"UNIFI_HOST":"your-unifi-controller-host","UNIFI_USERNAME":"your-username","UNIFI_PASSWORD":"your-password"}}}}
Fit and risk
Not for
- Users limited to cloud API access who need full device/client-level control (cloud modes are largely read-only)
- Enterprise deployments requiring production-grade audit logging, RBAC, or dry-run safeguards that are already fully implemented (per the README, these are still planned)
Required permissions
- UniFi controller address (local gateway IP or cloud API) and login credentials (username/password or API key)
- Direct network reachability to the controller (local gateway mode requires LAN access)
- Write access to firewall rules, networks/VLANs, WiFi, and device state if mutating tools are used
Risks and side effects
- The server can perform broad administrative operations on network infrastructure (restart/upgrade devices, modify firewall and WiFi settings); misconfiguration can disrupt network connectivity
- Credentials (API key or username/password) are configured as plaintext environment variables and must be handled carefully
- The README indicates local gateway mode defaults SSL certificate verification to false (UNIFI_LOCAL_VERIFY_SSL), which carries a man-in-the-middle risk
- The server.json manifest and the README describe different versions, packaging, and auth variables — copying either config verbatim without reconciling may fail to connect
- Dry-run mode, audit logging, and RBAC are documented as 'planned' rather than shipped, so they cannot be relied on as active safeguards
Troubleshooting
- First confirm which version/source is actually installed (npm manifest vs. PyPI/README) and match the corresponding environment variable names
- Verify UNIFI_API_TYPE (local/cloud-ea/cloud-v1, if applicable) matches actual network reachability; cloud modes cannot access individual devices or clients
- Check that mutating tools are called with the required confirm parameter
- If local gateway connections fail, check SSL verification settings and the gateway IP/port
- If using SSE/HTTP transport modes, confirm MCP_SERVER_PORT is free and the client URL configuration is correct
Use cases
Let an AI assistant query UniFi devices, clients, and network status
Create or adjust WiFi networks, VLANs, and firewall policies conversationally
Pull DPI stats like top bandwidth applications for troubleshooting
Aggregate analytics across multiple sites (limited functionality in cloud API modes)
Supported clients
Claude DesktopFull support
CursorFull support