unifi-mcp

Talk to your UniFi network.

An open-source Model Context Protocol server for Ubiquiti UniFi Network. It lets Claude and other AI assistants monitor and manage your sites, devices, clients, WiFi, firewall and more, all from one Docker container.

unifi-mcp.mattoddie.dev

Quick start · Documentation · Tool reference · Contributing

"Why is the lounge TV buffering?" The TV is on the Lounge AP at -78 dBm and 12 Mbps, and that AP's 5 GHz radio is at 81% channel utilisation on channel 36. Moving the AP to channel 149 or adding a wired backhaul should fix it. Want me to change the channel?

Ask about your network in plain English. The assistant picks from 132 tools to look things up and, if you allow it, make changes. Some examples:

• 🩺 "Give me a health check of the network."

• 🔎 "Which clients have a weak WiFi signal right now?"

• 🔐 "Review my firewall and port forwards for anything risky."

• 🔄 "Which devices have firmware updates, and when were they last rebooted?"

• 🎟️ "Create 10 one-day guest vouchers limited to 5 Mbps."

• 🧱 "Block the device called 'kids-tablet' until I unblock it."

Highlights

• 🐳 Docker-first. There's one small distroless image (ghcr.io/mattoddie/unifi-mcp, about 22 MB) for linux/amd64 and linux/arm64. It serves Streamable HTTP for a long-running service, or stdio for docker run -i.

• 🛡️ Safe by default. The server is read-only unless you turn on writes, and deleting configuration needs a second switch. Destructive tools are labelled so your MCP client asks before running them, and passwords and keys are redacted from output.

• 🧰 Broad coverage. It covers 14 toolsets: devices, clients, switch ports and PoE, WiFi, networks and VLANs, WAN, DNS, legacy and zone-based firewall, traffic rules and routes, IDS/IPS, VPN, RADIUS, hotspot vouchers, statistics, logs, admins and backups.

• 🎛️ Tunable. Expose only the toolsets you need, which keeps the model's context small and focused.

• 🔌 Works with your controller. Supports UniFi OS consoles (UDM, UDM Pro/SE, UCG, UDR, UX, Cloud Key Gen2+, UniFi OS Server) and legacy self-hosted Network applications. Auth is an API key or a local account.

• 🧪 Tested. The test suite runs against a mock controller on every build.

Related MCP server: UnifiyMe

Quick start

You need Docker, a UniFi controller and an MCP client such as Claude Code.

1. Get credentials. On a UniFi OS console, create an API key: UniFi Network → Settings → Control Plane → Integrations → Create API Key. On older controllers, use a local account instead.

2. Start the server.

mkdir unifi-mcp && cd unifi-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/unifi-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/unifi-mcp/main/example.env -o .env
# Edit .env: set UNIFI_URL, UNIFI_API_KEY and a random MCP_AUTH_TOKEN (required; e.g. `openssl rand -hex 32`).
# Recommended: pin the console's certificate with UNIFI_TLS_FINGERPRINT (see docs/security.md).
docker compose up -d

3. Connect your assistant.

claude mcp add --transport http unifi http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Now ask "How's my network doing?" in Claude Code.

Using Claude Desktop, VS Code, Cursor or Codex? See Connecting MCP clients. Prefer not to run a service? Use stdio mode with docker run -i.

Turning on changes

Out of the box the assistant can look but not touch. To let it make changes, add these to .env and run docker compose up -d:

UNIFI_ALLOW_WRITES=true      # restart devices, block clients, edit WiFi/firewall/networks…
UNIFI_ALLOW_DELETES=true     # also allow deleting configuration, forgetting clients… (needs writes too)
UNIFI_TOOLSETS=overview,devices,clients,wifi,monitoring   # optional: expose fewer tools

Read Security before turning on writes for a production network.

What it can do

See the tool reference for every tool and argument. Ready-made prompts like network_health_check, troubleshoot_client and security_review chain the tools together for common jobs.

Documentation

The docs are also published at unifi-mcp.mattoddie.dev/docs, with search.

Contributing

Contributions are very welcome, whether that's bug reports, compatibility reports from your hardware, docs or new tools. Read the contributing guide to get started, and please follow the code of conduct. To report a vulnerability, see the security policy. Please don't open a public issue for one.

License

MIT © Matt Oddie

unifi-mcp is an independent community project. It is not affiliated with, endorsed by or sponsored by Ubiquiti Inc. UniFi and Ubiquiti are trademarks of Ubiquiti Inc.