Getting started

This guide takes you from nothing to asking your first question about your network. It takes about ten minutes.

What you need

A UniFi Network controller. This can be a UniFi OS console (Dream Machine, Cloud Gateway, Dream Router, Express, Cloud Key Gen2+, UniFi OS Server) or a self-hosted UniFi Network application. See Compatibility for the full list.
A machine that runs Docker and can reach the controller over the network. This could be a NAS, a home server, a Raspberry Pi 4/5 or your laptop. The image supports both amd64 and arm64.
An MCP client, such as Claude Code, Claude Desktop, VS Code, Cursor or Codex.

1. Find your controller URL

This is the address you use to open the UniFi web interface, without any path:

Controller	Typical URL
UniFi OS console (UDM, UCG, UDR, UX, Cloud Key Gen2+)	`https://192.168.1.1` (the console’s LAN IP)
UniFi OS Server	`https://<server>:11443`
Legacy self-hosted Network application	`https://<server>:8443`

Use the local address, not unifi.ui.com. The server talks to the controller directly over your LAN.

2. Create credentials

There are two ways to authenticate. Use an API key if you can.

Option A: API key (UniFi OS, recommended)

Open UniFi Network → Settings → Control Plane → Integrations.
Click Create API Key, give it a name like unifi-mcp, and copy the key. You can’t see it again later.

API keys need UniFi Network 9.0 or later on a UniFi OS console. The key has the same permissions as the admin who created it.

Option B: Local account (any controller)

On UniFi OS, open UniFi OS → Admins & Users → Add Admin. On a legacy controller, open Settings → Admins.
Tick Restrict to local access only, then set a username and password.
Choose a role:
- View Only if you only want the assistant to read.
- Site Admin or a custom role with Network admin rights if you want to turn on writes.

3. Run the server

Create a folder and download the compose file and the example settings:

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 and set at least:

UNIFI_URL=https://192.168.1.1
UNIFI_API_KEY=your-api-key          # or UNIFI_USERNAME + UNIFI_PASSWORD
MCP_AUTH_TOKEN=a-long-random-string # generate one with: openssl rand -hex 32

Start it:

docker compose up -d
docker compose logs -f unifi-mcp

You should see a line like this:

unifi-mcp 1.0.0: controller https://192.168.1.1, site "default", auth API key, writes disabled, transport http
unifi-mcp listening on http://0.0.0.0:8080/mcp (bearer auth enabled)

Check that it’s up from another machine:

curl http://<docker-host>:8080/health
# {"status":"ok"}

4. Connect your assistant

For Claude Code:

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

Run claude mcp list to check that unifi shows as connected. For other clients, see Connecting MCP clients.

5. Ask something

Start a new conversation and try:

“List my UniFi sites and give me a quick health summary.”
“Which access points have the most clients?”
“Show me any alarms from the last day.”

The assistant calls tools like unifi_get_site_health and unifi_list_devices and summarises the results. In Claude Code you can also run the built-in prompts as slash commands, for example /mcp__unifi__network_health_check.

If something goes wrong, the tool’s error message usually says what to fix. Troubleshooting covers the common errors.

Next steps

Let it make changes. Set UNIFI_ALLOW_WRITES=true, and read Security first.
Expose fewer tools with UNIFI_TOOLSETS for a faster, more focused assistant. See Configuration.
Put it behind HTTPS if it’s reachable outside your LAN. See Deployment.
Learn what it can do in Using unifi-mcp and the tool reference.