UniFi

---

"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 145 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. For Claude Desktop there's also a one-click extension bundle (.mcpb) that needs no Docker.
• 🛡️ 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.
• 🔍 Preview and audit. Every write tool takes dry_run: true to show the request it would send, with a field-level diff of what would change, without changing anything. UNIFI_AUDIT_LOG records each change in a JSON Lines audit log.
• 🧰 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. See Keeping the tool list small.
• 🔌 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 (required; e.g. `openssl rand -hex 32`).
# For an https controller, also say how to check its certificate, or the server won't start.
# Recommended: pin it with UNIFI_TLS_FINGERPRINT (see docs/security.md). example.env sets
# UNIFI_VERIFY_SSL=false, which skips the check: remove it once the fingerprint is set.
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.

Claude Desktop in one click

On a Mac or Windows PC with Claude Desktop, you don't need Docker at all. Download the .mcpb bundle for your computer from the latest release, open it, and enter your controller URL, API key and certificate fingerprint in the settings. See Claude Desktop.

unifi-mcp is also listed in the MCP Registry as io.github.mattoddie/unifi-mcp, with the image (over stdio) and the bundles, so clients and directories that read the registry can install it.

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
UNIFI_AUDIT_LOG=stderr       # optional: log every change (or a file path; see docs/configuration.md)

Ask for a dry run to preview a change first: "Dry run: disable the guest WiFi. What would change?" 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, lock to an AP, forget
switching	Switch ports, port profiles, PoE power-cycling, port mirroring, link aggregation, LLDP neighbours
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, QoS rules, NAT rules, switch ACL rules, object-oriented network policies
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, traffic flows, DPI, speed tests, rogue APs, system log, sessions, anomalies, dashboards
admin	Site settings (including SNMP, mDNS and auto-backup), 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

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

🚀 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 145 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

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.