unifi-udm-pro-mcp
This server provides 40+ MCP tools for local, privacy-first management of UniFi UDM/UDM Pro/UDM SE and UniFi OS Cloud Gateways via native API keys (no cloud/2FA, ultra-low latency).
System & Monitoring: Get OS version/build/timezone/uptime, subsystem health (WAN/LAN/WLAN/VPN, CPU/RAM), sites, network events, security alarms, and trigger WAN speed tests.
Device Administration: List APs/switches/gateways with IP/MAC/status; reboot, upgrade, locate (flash LED), and power-cycle PoE ports.
Client Management: List active/historical clients; set aliases, static IPs, QoS profiles; block/unblock, reconnect, and forget clients.
Wi-Fi / WLAN (Full CRUD): List, create, update, delete SSIDs; change WPA passphrases; enable/disable Wi-Fi networks.
Networks & VLANs (Full CRUD): List, create, update, delete subnets and VLANs.
Firewall (Full CRUD): List, create, delete firewall rules; list/create IP and port groups.
Port Forwarding (Full CRUD): List, create, delete port forwarding rules.
Hotspot & QoS: List, create, revoke guest vouchers; list/create bandwidth rate-limiting QoS profiles.
Allows triggering WAN speed tests on the UDM Pro gateway to measure internet speed.
Provides tools for interacting with UniFi UDM Pro / UDM SE / Cloud Gateway devices via local API keys, enabling management of Wi-Fi networks, VLANs, firewall rules, port forwarding, switch ports, guest vouchers, QoS profiles, client devices, and device administration (reboot, upgrade, locate) directly on the local UDM Pro REST API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@unifi-udm-pro-mcp list my active clients and their bandwidth usage"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
UniFi UDM Pro MCP Server (unifi-udm-pro-mcp)
A high-performance, native Model Context Protocol (MCP) server for Ubiquiti UniFi Dream Machine (UDM / UDM Pro / UDM SE) and UniFi OS Cloud Gateways.
Unlike legacy UniFi MCP implementations that rely on cloud session cookies, username/passwords, or 2FA tokens, this MCP server connects directly to your local UDM Pro REST API using native Local API Keys (X-API-KEY).
Key Features
⚡ Ultra-Low Latency (10–30ms): Direct local LAN communication over HTTPS (
https://192.168.1.1).🔐 100% 2FA-Bypass & Continuous Uptime: Uses native UniFi API Keys. Sessions never expire or prompt for 2FA.
🛠️ 40 Comprehensive Tools: Complete CRUD (Create, Read, Update, Delete) coverage across Wi-Fi, VLANs, Firewall, Port Forwarding, Switch Ports, Guest Vouchers, QoS, and Devices.
🔏 Safe SSL Handling: Natively handles local self-signed SSL certificates without extra environment hacks.
🔒 Privacy-First: 100% local execution. No cloud proxies or external data telemetry.
Related MCP server: mcp-unifi
Available MCP Tools (40 Tools)
1. System & Subsystems
unifi_get_sysinfo- UDM Pro console OS version, build, timezone, uptime.unifi_get_health- Subsystem health (WAN 1/2, LAN, WLAN, VPN, ISP speed, CPU/RAM).unifi_list_sites- List all sites managed by controller.unifi_list_events- Recent network events and security logs.unifi_list_alarms- Active security alarms.unifi_run_speedtest- Trigger WAN speed test on UDM Pro gateway.
2. Device Administration
unifi_list_devices- Inventory of access points, switches, gateways, IP, MAC, status.unifi_reboot_device- Restart AP, Switch, or Gateway by MAC address.unifi_upgrade_device- Trigger firmware upgrade by MAC address.unifi_locate_device- Flash physical locator LED on AP or Switch.unifi_power_cycle_port- Power cycle PoE switch port by MAC and port index.
3. Client Devices & Control
unifi_list_clients- Real-time active clients, IP/MAC, signal, rx/tx bandwidth.unifi_get_all_clients_history- Historical record of all clients ever connected (100+ devices).unifi_set_client_name- Assign custom alias name to client device.unifi_set_client_fixed_ip- Assign static/fixed IP to client device.unifi_set_client_usergroup- Assign QoS bandwidth limit profile to client.unifi_block_client- Block client by MAC address.unifi_unblock_client- Unblock client by MAC address.unifi_reconnect_client- Force client to reconnect to nearest AP.unifi_forget_client- Remove offline client record from database.
4. Wi-Fi / WLAN (Full CRUD)
unifi_list_wlans- List SSIDs, WPA passphrases, bands, enabled status.unifi_create_wlan- Create new Wi-Fi network.unifi_update_wlan- Update Wi-Fi settings.unifi_delete_wlan- Delete Wi-Fi network.unifi_set_wlan_password- Instantly change WPA passphrase for SSID.unifi_set_wlan_status- Enable or disable Wi-Fi network on demand.
5. Networks & VLANs (Full CRUD)
unifi_list_networks- List subnets, VLANs, gateway IPs, DHCP ranges.unifi_create_network- Create new network subnet / VLAN.unifi_update_network- Update subnet settings.unifi_delete_network- Delete subnet / VLAN.
6. Firewall & Security (Full CRUD)
unifi_list_firewall_rules- List active firewall rules.unifi_create_firewall_rule- Create firewall rule (accept/drop/reject).unifi_delete_firewall_rule- Delete firewall rule by ID.unifi_list_firewall_groups- List IP & Port groups.unifi_create_firewall_group- Create IP or Port group.
7. Port Forwarding (Full CRUD)
unifi_list_port_forwards- List port forwarding rules.unifi_create_port_forward- Create port forward rule (WAN -> LAN).unifi_delete_port_forward- Delete port forward rule.
8. Hotspot & QoS
unifi_list_vouchers- List active guest hotspot vouchers.unifi_create_voucher- Create new guest vouchers by duration/count.unifi_revoke_voucher- Revoke guest voucher.unifi_list_user_groups- List bandwidth limit profiles.unifi_create_user_group- Create bandwidth limit profile (QoS max up/down).
Quick Start
Option 1: npx (Recommended)
No installation needed:
UNIFI_HOST=https://YOUR_UNIFI_HOST_IP UNIFI_API_KEY=your_key npx unifi-udm-pro-mcpOption 2: Docker
docker run -e UNIFI_HOST=https://YOUR_UNIFI_HOST_IP -e UNIFI_API_KEY=your_key ghcr.io/rodolfoconcepcion/unifi-udm-pro-mcpOption 3: Manual Install
git clone https://github.com/rodolfoconcepcion/unifi-udm-pro-mcp.git
cd unifi-udm-pro-mcp
npm install
UNIFI_HOST=https://YOUR_UNIFI_HOST_IP UNIFI_API_KEY=your_key node index.jsConfiguration
UNIFI_HOST must include the https:// protocol prefix (e.g., https://192.168.0.1). UniFi OS requires HTTPS for local REST API access. Self-signed SSL/TLS certificates on local console IPs are handled automatically.
Claude Desktop / Antigravity
Add to claude_desktop_config.json or Antigravity MCP settings:
{
"mcpServers": {
"unifi-udm-pro": {
"command": "npx",
"args": ["-y", "unifi-udm-pro-mcp"],
"env": {
"UNIFI_HOST": "https://YOUR_UNIFI_HOST_IP",
"UNIFI_API_KEY": "YOUR_UNIFI_LOCAL_API_KEY"
}
}
}
}VS Code (GitHub Copilot)
Add to your project's .vscode/mcp.json or user settings:
{
"servers": {
"unifi-udm-pro": {
"command": "npx",
"args": ["-y", "unifi-udm-pro-mcp"],
"env": {
"UNIFI_HOST": "https://YOUR_UNIFI_HOST_IP",
"UNIFI_API_KEY": "YOUR_UNIFI_LOCAL_API_KEY"
}
}
}
}Cursor / Windsurf
Add to your MCP settings (Settings → MCP Servers):
{
"mcpServers": {
"unifi-udm-pro": {
"command": "npx",
"args": ["-y", "unifi-udm-pro-mcp"],
"env": {
"UNIFI_HOST": "https://YOUR_UNIFI_HOST_IP",
"UNIFI_API_KEY": "YOUR_UNIFI_LOCAL_API_KEY"
}
}
}
}How to Obtain a UniFi API Key
Log into your UniFi OS Console (e.g.,
https://YOUR_UNIFI_HOST_IPor your UDM IP).Click Console Settings (gear icon in bottom left) → System → Integrations (or Integrations tab).
Under API Key, click Create New API Key.
Copy and save the generated key immediately (it is only displayed once).
Contributing
See CONTRIBUTING.md for guidelines.
Security
See SECURITY.md for vulnerability reporting.
License
MIT License - See LICENSE for details.
Available Tools
43 toolsunifi_block_clientB
Block a client device on the network by MAC address.
Inputs: mac (required).
unifi_create_firewall_groupB
Create a new firewall IP or Port group.
Inputs: name (required), group_type (required), group_members.
unifi_create_firewall_ruleC
Create a new firewall rule.
Inputs: name (required), action (required), ruleset (required), dst_address, +1 more.
unifi_create_networkC
Create a new network subnet / VLAN.
Inputs: name (required), ip_subnet (required), vlan, purpose.
unifi_create_port_forwardC
Create a new port forwarding rule.
Inputs: fwd (required), name (required), dst_port (required), fwd_port (required), +1 more.
unifi_create_user_groupC
Create a new bandwidth rate-limiting user group.
Inputs: name (required), qos_rate_max_up, qos_rate_max_down.
unifi_create_voucherC
Create new guest hotspot Wi-Fi vouchers.
Inputs: minutes (required), count, quota.
unifi_create_wlanC
Create a new Wi-Fi SSID network.
Inputs: name (required), x_passphrase (required), enabled, is_guest.
unifi_delete_firewall_ruleA
Delete a firewall rule by ID.
Inputs: rule_id (required).
unifi_delete_networkB
Delete a network subnet / VLAN by ID.
Inputs: network_id (required).
unifi_delete_port_forwardA
Delete a port forwarding rule by ID.
Inputs: pfwd_id (required).
unifi_delete_wlanB
Delete a Wi-Fi SSID network by WLAN ID.
Inputs: wlan_id (required).
unifi_forget_clientA
Forget/remove an offline client record from controller database by MAC address.
Inputs: macs (required).
unifi_get_all_clients_historyA
Fetch historical record of all client devices that have ever connected to the network.
Inputs: no named parameters.
unifi_get_healthA
Get health status of UniFi UDM Pro network subsystems (WAN, LAN, WLAN, VPN, ISP speed & CPU/Memory usage).
Inputs: no named parameters.
unifi_get_sysinfoA
Get UniFi UDM Pro console system info, OS version, controller build, timezone, and uptime.
Inputs: no named parameters.
unifi_list_alarmsA
List active network security alarms and system alerts.
Inputs: no named parameters.
unifi_list_clientsA
List active connected client devices on the UniFi network (IP, MAC, hostname, signal, bandwidth, network).
Inputs: no named parameters.
unifi_list_devicesA
List all UniFi access points, switches, gateways, uptime, IP addresses, and adoption status.
Inputs: no named parameters.
unifi_list_eventsB
Fetch recent network events, client connects/disconnects, and security alerts.
Inputs: limit.
unifi_list_firewall_groupsA
List configured firewall IP & port groups.
Inputs: no named parameters.
unifi_list_firewall_rulesA
List configured firewall rules, rule numbers, action (accept/drop/reject), and interface bindings.
Inputs: no named parameters.
unifi_list_networksA
List all configured network subnets, VLANs, gateway IPs, DHCP ranges, and DNS settings.
Inputs: no named parameters.
unifi_list_port_forwardsA
List configured port forwarding rules (forwarded IP, external/internal ports, protocol).
Inputs: no named parameters.
unifi_list_sitesA
List all sites managed on this UniFi controller.
Inputs: no named parameters.
unifi_list_user_groupsA
List bandwidth rate-limiting user groups (QoS max upload / download speed).
Inputs: no named parameters.
unifi_list_vouchersA
List active guest hotspot vouchers.
Inputs: no named parameters.
unifi_list_wlansA
List all configured Wi-Fi SSIDs, passphrases, security modes, frequency bands, and enabled status.
Inputs: no named parameters.
unifi_locate_deviceA
Flash the LED on a UniFi Access Point or Switch to locate it physically.
Inputs: mac (required), enable (required).
unifi_power_cycle_portB
Power cycle (restart) a PoE switch port on a UniFi Switch by device MAC and port index.
Inputs: mac (required), port_idx (required).
unifi_reboot_deviceA
Restart/Reboot a UniFi device (Access Point, Switch, or Gateway) by MAC address.
Inputs: mac (required).
unifi_reconnect_clientA
Force a client device to reconnect to the nearest access point by MAC address.
Inputs: mac (required).
unifi_revoke_voucherB
Revoke/Delete a guest hotspot voucher by ID.
Inputs: voucher_id (required).
unifi_run_speedtestA
Trigger a WAN speedtest directly on the UDM Pro gateway.
Inputs: no named parameters.
unifi_set_client_fixed_ipB
Assign a static/fixed IP address to a client device on the network.
Inputs: ip (required), mac (required), use_fixed_ip (required).
unifi_set_client_nameA
Assign an alias or custom display name to a client device by MAC address.
Inputs: mac (required), name (required).
unifi_set_client_usergroupB
Assign a bandwidth rate-limiting profile (User Group) to a client device.
Inputs: user_id (required), usergroup_id (required).
unifi_set_wlan_passwordC
Quickly update WPA passphrase for a Wi-Fi SSID network.
Inputs: wlan_id (required), password (required).
unifi_set_wlan_statusB
Enable or disable a Wi-Fi SSID network on demand.
Inputs: enabled (required), wlan_id (required).
unifi_unblock_clientA
Unblock a previously blocked client device on the network by MAC address.
Inputs: mac (required).
unifi_update_networkB
Update configuration of an existing network subnet / VLAN by ID.
Inputs: network_id (required), name, ip_subnet.
unifi_update_wlanC
Update configuration of an existing Wi-Fi network by WLAN ID.
Inputs: wlan_id (required), name, enabled, x_passphrase.
unifi_upgrade_deviceB
Trigger firmware upgrade on a UniFi device by MAC address.
Inputs: mac (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Most tools target distinct resource-action pairs, and the descriptions clarify their purpose. A minor overlap exists between update_wlan and set_wlan_password, but the quick-update intent of the latter reduces confusion.
Every tool follows the consistent `unifi_verb_noun` snake_case pattern. Verbs like list/get/create/update/delete/set are used predictably, making the surface easy to navigate.
With 43 tools, the server is well beyond the 25-tool threshold typically considered manageable. While the UniFi domain is broad, this many tools risks overwhelming agents and increases selection difficulty.
The set covers most core workflows for WLANs, networks, devices, and clients. However, firewall rules, firewall groups, port forwards, and user groups lack update or delete operations, creating dead ends for management flows.
Maintenance
Related MCP Connectors
Hosted MCP servers for MSP tools: ConnectWise, NinjaOne, Microsoft 365, SentinelOne, Pax8 and more.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables comprehensive management of UniFi Network infrastructure through 24 tools for monitoring and controlling devices, clients, wireless networks, security, and guest access. Supports network administration tasks like device restarts, client blocking, WLAN configuration, and backup creation.14 npmMIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server for self-hosted UniFi gateway management, providing tools for devices, networks, WiFi, firewall rules, switch port profiles, connected clients, and a one-shot IoT network creation with rollback.31MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for UniFi Network Controller enabling AI assistants to manage UniFi infrastructure via natural language. It supports firewall rules, IPv6, and uses lazy/eager tool modes to minimize context usage.7Mozilla Public 2.0
- AlicenseAqualityDmaintenanceMCP server providing typed, safety-gated access to UniFi Network consoles via the official API, enabling management of devices, clients, networks, WiFi, firewall policies, and more.1636 npm2MIT