Skip to content
unifi-mcp

Configuration

unifi-mcp is configured entirely through environment variables. With Docker Compose, put them in .env. Copy example.env to get started.

The server checks the configuration at startup. If something is wrong, it exits with a clear message such as UNIFI_ALLOW_DELETES=true also requires UNIFI_ALLOW_WRITES=true. If the container keeps restarting, check docker compose logs.

Controller connection

Section titled “Controller connection”
Variable Default Description
UNIFI_URL required Controller URL, for example https://192.168.1.1 or https://unifi.local:8443. Don’t include a path.
UNIFI_API_KEY API key. UniFi OS consoles only, Network 9.0+. Takes priority over username/password.
UNIFI_USERNAME Local account username, used when no API key is set.
UNIFI_PASSWORD Local account password.
UNIFI_SITE default Site to use when a tool call doesn’t name one. Use the site’s API name, which is the name field from unifi_list_sites (e.g. default, x7k2pq9d), not its display name.
UNIFI_VERIFY_SSL false Verify the controller’s TLS certificate. Leave it false for the self-signed certificate that consoles ship with. Set it to true if you’ve installed a trusted certificate.
UNIFI_CONTROLLER_TYPE auto auto, unifi-os or legacy. With auto, the server detects the type on first use. Set it explicitly if detection fails, for example behind an unusual reverse proxy.
UNIFI_TIMEOUT_MS 30000 Timeout for each controller request, in milliseconds.

Boolean variables accept true/false, 1/0, yes/no and on/off.

How authentication works

Section titled “How authentication works”
  • API key: every request sends an X-API-KEY header. There are no sessions and no logins.
  • Username/password: the server logs in on first use and keeps the session cookie (plus the CSRF token on UniFi OS). If the session expires, it logs in again and retries the request once. Several requests arriving together share a single login.

What the assistant may do

Section titled “What the assistant may do”
Variable Default Description
UNIFI_ALLOW_WRITES false Register tools that change state: restarting devices, blocking clients, editing WiFi, firewall, networks and so on.
UNIFI_ALLOW_DELETES false Also register tools that delete configuration, such as networks, WLANs, firewall rules or sites. Requires UNIFI_ALLOW_WRITES=true.
UNIFI_TOOLSETS all Comma-separated list of toolsets to expose.

Tools that aren’t allowed are not registered at all. The assistant can’t see them, so it can’t call them or be talked into calling them.

MCP transport

Section titled “MCP transport”
Variable Default Description
MCP_TRANSPORT http in the Docker image (stdio when run with Node directly) http for Streamable HTTP, or stdio.
MCP_HTTP_HOST 0.0.0.0 Address to listen on (HTTP only).
MCP_HTTP_PORT 8080 Port to listen on (HTTP only).
MCP_AUTH_TOKEN When set, every request to /mcp must send Authorization: Bearer <token>. Set this whenever anything other than you can reach the port.
MCP_ALLOWED_HOSTS Comma-separated allow-list of Host header values, such as unifi-mcp.lan,unifi-mcp.lan:8080. Requests with any other Host are rejected, which protects against DNS-rebinding attacks from web pages in your browser.

The HTTP server exposes these endpoints:

Path Method Purpose
/mcp POST The MCP endpoint (stateless Streamable HTTP, JSON responses). Other methods return 405.
/health, /healthz GET Liveness check. Returns {"status":"ok"} and doesn’t contact the controller.

Docker secrets (_FILE variables)

Section titled “Docker secrets (_FILE variables)”

Every variable can also be read from a file: set <NAME>_FILE to the file’s path. Leading and trailing whitespace is trimmed. This works with Docker secrets and Kubernetes secret volumes:

services:
  unifi-mcp:
    image: ghcr.io/mattoddie/unifi-mcp:latest
    environment:
      UNIFI_URL: https://192.168.1.1
      UNIFI_API_KEY_FILE: /run/secrets/unifi_api_key
      MCP_AUTH_TOKEN_FILE: /run/secrets/mcp_auth_token
    secrets: [unifi_api_key, mcp_auth_token]
    ports: ["8080:8080"]


secrets:
  unifi_api_key:
    file: ./secrets/unifi_api_key.txt
  mcp_auth_token:
    file: ./secrets/mcp_auth_token.txt

If both NAME and NAME_FILE are set, the file wins.

Choosing toolsets

Section titled “Choosing toolsets”

Every tool’s name, description and argument schema is sent to the model, which uses up context. With all 132 tools enabled, that’s a lot of text, and some clients warn about or cap the number of tools. Expose only what you need:

Toolset Tools Use it for
overview 3 Sites and health. Always include it.
devices 19 APs, switches, gateways, firmware
clients 8 Who’s connected, blocking
switching 7 Switch ports, PoE
wifi 4 SSIDs
networks 13 VLANs, WAN, DNS, bandwidth profiles
firewall 20 Port forwards, rules, policies, zones, traffic rules
routing 6 Static routes, traffic routes
security 7 IDS/IPS, country blocking, content filters
vpn 9 VPNs, RADIUS
hotspot 10 Vouchers, guests
monitoring 13 Events, alarms, stats, logs
admin 12 Settings, admins, backups
raw 1 Any API path. Handy, but gives broad access.

The counts include write and delete tools, so a read-only setup registers far fewer tools. Some suggested sets:

Goal UNIFI_TOOLSETS
Everyday monitoring overview,devices,clients,monitoring
WiFi tuning overview,devices,clients,wifi,monitoring
Firewall and security review overview,networks,firewall,routing,security,monitoring
Guest network operations overview,clients,hotspot,wifi
Everything (default) all

Example configurations

Section titled “Example configurations”

Read-only monitoring (the safest setup):

Terminal window
UNIFI_URL=https://192.168.1.1
UNIFI_API_KEY=...
MCP_AUTH_TOKEN=...
UNIFI_TOOLSETS=overview,devices,clients,monitoring

Day-to-day admin. Changes are allowed, but nothing can be deleted:

Terminal window
UNIFI_URL=https://192.168.1.1
UNIFI_API_KEY=...
MCP_AUTH_TOKEN=...
UNIFI_ALLOW_WRITES=true

Legacy self-hosted controller with a trusted certificate:

Terminal window
UNIFI_URL=https://unifi.example.lan:8443
UNIFI_USERNAME=mcp
UNIFI_PASSWORD=...
UNIFI_VERIFY_SSL=true
UNIFI_CONTROLLER_TYPE=legacy
MCP_AUTH_TOKEN=...