Troubleshooting complex homelab networking issues (VLAN misconfigurations, AP channel congestion, rogue IoT devices, PoE budget limits) usually requires clicking through half a dozen sub-menus in the UniFi Network Controller.

In this post, I explain how we built a containerized UniFi MCP Server that connects your UniFi Controller to AI pair-programming agents like Antigravity, giving the agent live introspection and diagnostic control over your entire network.

Why Expose UniFi to AI via MCP?

Instead of manually logging into 192.168.1.1 to check client lists, an MCP-connected agent can:

• Instant Client Lookup: “Find IP, MAC, and connected switch port for device esp32-box-voice.”
• VLAN & Port Audits: “List all switch ports configured with VLAN 30 (IoT) and check their link speeds.”
• AP Radio Telemetry: “Which Access Point has the highest channel utilization on 5GHz right now?”
• Batch Operations: Execute safe batch operations across multiple switches with structured tool confirmations.

Docker Deployment: mcp-unifi

We run mcp-unifi as a lightweight container on our primary Docker host (10.10.20.15):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

services:
  mcp-unifi:
    image: ghcr.io/homelab/mcp-unifi:latest
    container_name: mcp-unifi
    restart: unless-stopped
    ports:
      - "32000:32000"
    environment:
      - UNIFI_HOST=https://192.168.1.1
      - UNIFI_USER=mcp-agent
      - UNIFI_PASS=${UNIFI_PASSWORD}
      - UNIFI_SITE=default
      - UNIFI_VERIFY_SSL=false
      - MCP_PORT=32000
    networks:
      - homelab-net

Exposed Tool Definitions

The UniFi MCP server exposes 5 high-impact tools to the agent:

1. unifi_tool_index: Returns a comprehensive catalog of all network query methods.
2. unifi_execute: Runs targeted API endpoints against the controller (e.g. stat/sta, stat/device, rest/networkconf).
3. unifi_batch: Executes sequential multi-device commands (e.g., restarting PoE on specific ports).
4. unifi_load_tools: Dynamically generates schema definitions for deep network querying.

Example Agent Diagnostic Session:

1
2
3
4
5
6
7
8

User: "Antigravity, why is my Home Assistant camera stream lagging?"

Agent:
-> Calling mcp-unifi: unifi_execute(endpoint="stat/sta", filter={"mac": "dc:a6:32:..."})
<- Returns: RSSI -84 dBm, TX Rate 12 Mbps, Channel 36 (Congestion 78%)

Agent Response:
"The camera is experiencing poor WiFi signal (-84 dBm) and high channel congestion (78%) on AP-LivingRoom. Moving it to AP-Hallway on Channel 149 will restore full 60fps throughput."

Having your network topology available to your AI assistant turns routine network troubleshooting into a single conversational query.