Skip to main content
Glama

UniFi UDM Pro MCP Server (unifi-udm-pro-mcp)

CI npm version unifi-udm-pro-mcp MCP server Glama Score License: MIT MCP Protocol Node.js GitHub stars

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

No installation needed:

UNIFI_HOST=https://YOUR_UNIFI_HOST_IP UNIFI_API_KEY=your_key npx unifi-udm-pro-mcp

Option 2: Docker

docker run -e UNIFI_HOST=https://YOUR_UNIFI_HOST_IP -e UNIFI_API_KEY=your_key ghcr.io/rodolfoconcepcion/unifi-udm-pro-mcp

Option 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.js

Configuration

NOTE

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

  1. Log into your UniFi OS Console (e.g., https://YOUR_UNIFI_HOST_IP or your UDM IP).

  2. Click Console Settings (gear icon in bottom left) → System → Integrations (or Integrations tab).

  3. Under API Key, click Create New API Key.

  4. 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 tools
unifi_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

    B3.1/5.0

    Scored across 43 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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.
      31
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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.
      7
      Mozilla Public 2.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      16
      36 npm
      2
      MIT