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://192.168.1.1 UNIFI_API_KEY=your_key npx unifi-udm-pro-mcp

Option 2: Docker

docker run -e UNIFI_HOST=https://192.168.1.1 -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://192.168.1.1 UNIFI_API_KEY=your_key node index.js

Configuration

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://192.168.1.1",
        "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://192.168.1.1",
        "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://192.168.1.1",
        "UNIFI_API_KEY": "YOUR_UNIFI_LOCAL_API_KEY"
      }
    }
  }
}

How to Obtain a UniFi API Key

1. Log into your UniFi Console (https://192.168.1.1/).

2. Go to Control Plane Settings → Integrations (or API Keys).

3. Click Add API Key and copy the generated key.

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for vulnerability reporting.

License

MIT License - See LICENSE for details.