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).
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.
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.
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.
| 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.
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.