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.

---

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.