---
title: "Controlling UniFi Networks with AI: Building a Custom UniFi MCP Server for Topology & Diagnostics"
date: "2026-10-14T10:00:00+02:00"
tags: ["UniFi", "Networking", "MCP", "FastMCP", "Docker", "Antigravity", "Homelab"]
categories: ["AI & LLM Ops", "Networking"]
---

![Controlling UniFi Networks with AI via Custom UniFi MCP Server][1]

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.

<!--more-->

## 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`):

```yaml
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:
```text
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.

[1]: /images/uploads/2026/10/controlling-unifi-network-mcp-server.webp?v=2