unifi-console-mcp

unifi-console-mcp

An MCP server for the undocumented UniFi OS and Network console APIs, with typed, gated write tools. Most UniFi MCP servers use the supported Integration API or a fixed set of legacy calls. This one is driven by an OpenAPI spec of the console’s own API (src/unifi_console_mcp/openapi.yaml), so the tool surface can keep growing, and it adds safe, previewed configuration changes for the things the supported API does not cover.

Read this first. The APIs this server uses are not documented or supported by Ubiquiti and can change with any update. The write tools were proven live against one console (Cloud Key Gen2 Plus) running Network 11.0.81. Anything else is untested. Writes are off by default. If you turn them on, an AI client can change your network, including DNS, firewall rules and the WAN. Start with read-only, use a dedicated account, keep a backup, and read every preview before confirming. Provided as-is, without warranty (see LICENSE).

What it does

Generic tools reach every operation in the spec (about 180) without registering 180 tools:

Tool Purpose
unifi_console_list_operations Search the spec by words, tag or access level
unifi_console_describe_operation Parameters, body schema and the spec’s own warnings
unifi_console_read_operation Run one read operation (including the read-only POST queries). Annotated read-only, so a client can allow it without prompting
unifi_console_call_operation File downloads and gated safe writes (generate a backup or support file). Still runs reads, but is annotated as able to write; refuses configuration writes

Curated read tools for areas other servers skip: unifi_console_session_status, unifi_console_system_log, unifi_console_firewall_policy_hits (find unused rules), unifi_console_poe_overview, unifi_console_switch_port_detail, unifi_console_backup, unifi_console_support_file, unifi_console_gateway_config (the config the controller sent the gateway, with policy drift), unifi_console_access_review.

Typed write tools (all off until enabled; see docs/write-tools.md): port forwards, network lists, clients (edit and block/unblock/forget/reconnect), static DNS, client groups, Dynamic DNS, traffic and QoS objects, dashboard QoS rules, application blocks, devices (locate, restart, update, adopt, remove), DNS over HTTPS, firewall policies, switch ports, Wi-Fi, networks/VLANs, the WAN, syslog, data retention and logging levels.

How writes stay safe

Every write is two steps: confirm=false returns a read-only preview (before, after, diff, warnings, a fingerprint); confirm=true with that fingerprint applies it. The server re-reads the object first (a stale preview is refused), journals the attempt, sends the change, reads it back, verifies it, and returns the diff plus the exact rollback call. Risky entities (tier C) also need an approval_note, and the riskiest have an automatic restore if a DNS or connectivity check fails afterwards. Details: docs/write-safety.md.

Quick start

Requires Python 3.12+ and uv.

git clone https://github.com/jaseonline/unifi-console-mcp.git
cd unifi-console-mcp
uv sync
uv run pytest            # unit tests, no console needed
uv run unifi-console-mcp # stdio server

Create a dedicated local UniFi account for the server, then set the environment variables below and add the server to your MCP client. Claude Desktop example (claude_desktop_config.json):

{
  "mcpServers": {
    "unifi-console": {
      "command": "uv",
      "args": ["--directory", "/path/to/unifi-console-mcp", "run", "unifi-console-mcp"],
      "env": {
        "UNIFI_LOCAL_HOST": "192.168.1.2",
        "UNIFI_MCP_USERNAME": "your-local-account",
        "UNIFI_MCP_PASSWORD": "from-your-password-manager",
        "UNIFI_CONSOLE_CERT_SHA256": "pin-the-console-certificate-here"
      }
    }
  }
}

More in docs/getting-started.md.

Claude Desktop extension. Instead of editing claude_desktop_config.json, you can build an MCP Bundle (uv run mcpb/build.py) and install the .mcpb with a double-click: Claude Desktop shows a settings form and keeps the password and API key in the operating system’s secure storage. Blank form fields fall back to the environment variables below. See mcpb/README.md.

Configuration

Variable Meaning
UNIFI_LOCAL_HOST Console address, e.g. 192.168.1.2
UNIFI_LOCAL_PORT / UNIFI_DEFAULT_SITE HTTPS port (default 443) / site name (default default); UNIFI_NETWORK_PORT / UNIFI_NETWORK_SITE are also read
UNIFI_MCP_USERNAME / UNIFI_MCP_PASSWORD Dedicated local account (no MFA)
UNIFI_MCP_API_KEY Integration API key (only for Integration operations)
UNIFI_SITE_MANAGER_API_KEY Site Manager key from unifi.ui.com > API, for the read-only cloud operations on api.ui.com (not the Integration key)
UNIFI_CONSOLE_CERT_SHA256 Pin the console certificate by SHA-256 fingerprint (preferred)
UNIFI_LOCAL_VERIFY_SSL false to skip certificate checks (not recommended)
UNIFI_CONSOLE_ENABLE_WRITES true to allow writes (default false)
UNIFI_CONSOLE_WRITE_ENTITIES Comma-separated entities that may be written, e.g. port_forward,static_dns,qos_rule (default none)
UNIFI_CONSOLE_JOURNAL_DIR Change journal (default ~/.unifi-console-mcp/journal)
UNIFI_CONSOLE_DOWNLOAD_DIR Where backups and support files are saved (default ~/.unifi-console-mcp/downloads)
UNIFI_HOME_DOMAIN Your local DNS domain; static DNS names outside it trigger a warning (default example.home)
UNIFI_CONSOLE_DNS_PROBE_SERVER / _WINDOW DNS safety probe server and retry window (seconds)
UNIFI_CONSOLE_INTERNET_PROBE TCP endpoints the WAN safety net must reach (default 1.1.1.1:443,9.9.9.9:443)
UNIFI_CONSOLE_MAX_CHARS Response size budget (default 40000)
UNIFI_CONSOLE_SPEC_PATH Use a spec file other than the bundled one
UNIFI_CONSOLE_LOG_LEVEL Server log level: DEBUG, INFO (default), WARNING, ERROR or CRITICAL. Logs go to stderr, which the client writes to its MCP log, never to the chat

On Windows, a variable missing from the server’s own environment is also read from your persistent user and then system environment variables (the registry), so values set with setx or System Properties work even when the client did not pass them on.

The username, password, API key and Site Manager API key are checked in this order: a filled-in form field, then a password-manager credential cache (Windows Credential Manager, service unifi-mcp-cache, entries unifi-mcp/<field>; needs the keyring package, and UNIFI_CONSOLE_KEYRING=off skips it), then the variables above. The cache comes before the registry so a stale variable cannot override a rotated secret.

Secrets for Wi-Fi passphrases and Dynamic DNS tokens come from UNIFI_WIFI_<NAME> and UNIFI_DDNS_<NAME> environment variables only; they are never accepted as tool arguments and never appear in previews or the journal.

Documentation

Status

Proof of concept, actively developed. Unit tests use an in-memory fake console. Live checks (scripts/*_live_check.py) create and delete only throwaway objects with a zz- prefix, except where a script says otherwise. Run them against your own console only after reading them.

Licence

MIT