unifi-mcp：用自然语言管理 UniFi 网络的 MCP 服务器

"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 image (ghcr.io/mattoddie/unifi-mcp) 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.

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 (e.g. `openssl rand -hex 32`)
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 (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

Toolset	What's covered
`overview`	Sites, controller info, site health
`devices`	Device status and details, restart/locate/provision, firmware upgrades (also rolling), radios, PoE outlets, adoption, RF scans, AP groups
`clients`	Online and known clients, block/unblock, reconnect, names, fixed IPs, forget
`switching`	Switch ports, port profiles, PoE power-cycling
`wifi`	WLANs (SSIDs, security, VLANs, bands), WiFi QR codes
`networks`	Networks/VLANs and DHCP, WAN, local DNS records, bandwidth profiles, dynamic DNS
`firewall`	Port forwards, firewall rules and groups, zone-based policies and zones, traffic rules
`routing`	Static routes, policy-based traffic routes
`security`	IDS/IPS threat management, threat log, country blocking, content filtering
`vpn`	VPN servers and site-to-site VPNs, RADIUS profiles and accounts
`hotspot`	Vouchers, hotspot operators, guest authorization, guest portal
`monitoring`	Events, alarms, traffic reports, DPI, speed tests, rogue APs, system log, sessions, anomalies, dashboards
`admin`	Site settings, admins, backups, controller updates, sites
`raw`	An escape hatch that calls any controller API path

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


🚀 Getting started	Step-by-step setup, from credentials to first question
🔌 Connecting MCP clients	Claude Code, Claude Desktop, VS Code, Cursor, Codex, stdio mode
⚙️ Configuration	Every environment variable, Docker secrets, toolsets
🐳 Deployment	Compose, image tags, upgrades, TLS reverse proxy, hardening
💬 Using unifi-mcp	Example conversations, prompts, how saves and secrets work
🧰 Tool reference	All 132 tools and 5 prompts, generated from the code
🛡️ Security	Threat model, least privilege, safe write setups
📡 Compatibility	Supported controllers and versions, API caveats
🩹 Troubleshooting	Common errors and how to fix them
🛠️ Development	Architecture, adding a tool, testing

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

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.