UniFi

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](https://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 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 "

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

See the [tool reference](docs/tools.md) 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](https://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.*