unifi-console-mcp

Who and what can access the console: admin accounts, custom roles and API keys (keys masked).

Useful for least-privilege reviews of integration accounts. Needs read access to UniFi OS users. Returns JSON: {"ok", "data": {"admins": [...], "roles": [...], "api_keys": [...]}}.

List, create or download UniFi OS console backups (whole console, not just the Network app).

list is read-only. create makes a new backup on the console and needs UNIFI_CONSOLE_ENABLE_WRITES=true and confirm=true. download builds a fresh archive and saves it under the server's download folder (never returned here; it contains credentials) and needs confirm=true. Console-level calls need the MCP account's Control Plane permission raised from View to Admin.

Returns JSON: {"ok", "data": [...]} for list, or {"ok", "saved_file": {"path", "bytes", "sha256"}}.

Call one spec operation on the console. Reads run immediately; configuration writes are refused.

Read-only POST queries (system log, traffic flows) are treated as reads. File downloads (backups, support files) are saved to disk, never returned, and need confirm=true. Safe writes (generate a support file or backup) also need UNIFI_CONSOLE_ENABLE_WRITES=true on the server. Secrets (x_* fields, passwords, keys) are always redacted. Large results are cut to fit; use fields/search/limit/offset to narrow them.

Returns JSON: {"ok": true, "operation", "http_status", "meta"?, "data"} or {"ok": false, "error"}.

Preview, then apply, a change to one known client: alias, note, fixed IP and Local DNS record.

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. The client is re-read first, so a stale preview is refused. A fixed IP is checked against the real LAN subnets, the gateway and broadcast addresses, other clients' fixed IPs and the addresses in use right now; a Local DNS name is checked against other clients and the static DNS records. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'client' in UNIFI_CONSOLE_WRITE_ENTITIES. After applying, the client is read back and the result reports verified true/false, the diff, and the exact rollback call. Every write is journalled. A fixed IP takes effect when the client next renews its lease.

Preview, then apply, a command for one client: block, unblock, reconnect or forget.

Two steps, always: call with confirm=false to get a read-only preview (the client, the request, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. block and unblock are read back and are each other's rollback. reconnect disconnects a connected wireless client once. forget deletes an offline client's history, name, note, fixed IP and Local DNS record for good, so it also needs discard_history=true and has no rollback. UniFi devices are refused. Applying needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'client' in UNIFI_CONSOLE_WRITE_ENTITIES (the same switch as the client record tool). Every command is journalled.

Preview, then apply, a change to the console's client groups (named sets of client MAC addresses used by policies).

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, what uses the group, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. The group is re-read first, so a stale preview is refused. Members are MAC addresses (any common spelling is normalised to aa:bb:cc:dd:ee:ff); use add_members/remove_members to change a few, or members to replace all. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'client_group' in UNIFI_CONSOLE_WRITE_ENTITIES. A group that firewall policies or traffic objects still use cannot be deleted, and editing one warns that the change takes effect for them at once. The console only accepts the whole group, so updates send all of it. After applying, the group is read back and the result reports verified true/false, the diff, and the exact rollback call. Every write is journalled.

Preview, then apply, a change to how long the console keeps statistics and events (Control Plane > Network data retention).

Two steps, always: call with confirm=false to get a read-only preview (the retention fields only: before, after, diff, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. Fields: data_retention_setting_preference (auto or manual) and, with manual, hours_5minutes, hours_hourly, hours_daily, hours_monthly, hours_others. The rest of the group (auto-backup, analytics and a Google Maps key) is sent back exactly as read and never shown. Shortening retention deletes older data at the next prune; longer retention uses more storage. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'data_retention' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.

Show an operation's parameters, request-body schema, access level and description from the spec.

Does not call the console. Returns JSON with "parameters" (name, in, required, description), "body_schema" (resolved JSON schema or null), "access" and "description". Descriptions often record quirks such as 'Read-only despite POST' or which fields hold secrets, so read them before calling.

Preview, then apply, a change to the gateway's DNS over HTTPS (DoH) setting. Tier C: it can stop DNS for the whole network.

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, the safety probe result, a fingerprint); call again with the same fields plus confirm=true, that fingerprint and an approval_note to apply. Fields: state (off, auto, manual or custom), server_names (manual) and custom_servers (custom); the list that does not apply is cleared, as the UI does. Before applying, DNS is tested through the gateway; if it is already failing, the change is refused. After applying, DNS is tested again and, if it fails, the previous values are put back automatically (once) and the result says applied=false with auto_restored=true. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'doh' in UNIFI_CONSOLE_WRITE_ENTITIES. SSL inspection is a separate setting and is not changed here. Every write is journalled; scripts/doh_restore.py can put the last values back from the journal.

Preview, then apply, the creation, update or deletion of a Dynamic DNS entry on the gateway.

Two steps, always: call with confirm=false to get a read-only preview (after, warnings, errors, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. An update keeps the entry's id and sends the whole entry; because the console never shows the stored token, an update must be given token_env too (the current token if only other fields change, or the new one when rotating it). The provider token is never a tool argument: pass token_env, the name of a UNIFI_DDNS_* environment variable in the server's environment. The token is write-only, so it is not read back (the result lists it under secret_fields_not_verified) and it is not journalled. Deleting an entry discards its token for good: the delete needs discard_token=true, and its rollback can only recreate the entry with a fresh token. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'dynamic_dns' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.

Preview, then apply, a change to one custom zone-based firewall policy. Tier C: it can cut or expose the network.

Actions: create (switched off unless enabled=true), update, enable, disable, delete, move (position first, last, before or after relative_to, inside the policy's own zone pair). Two steps, always: call with confirm=false for a read-only preview (before, after, diff, what the policy matches in words, hits, warnings, errors, a fingerprint); call again with the same fields plus confirm=true, that fingerprint and an approval_note to apply. System-defined policies and the generated "(Return)" copies are never changed. An enabled ALLOW from External that matches everything, or an enabled BLOCK/REJECT that cuts DNS/DHCP/internet for the console's own network, is refused unless acknowledge_exposure / acknowledge_outage is passed. A change touching an enabled policy is wrapped in a DNS test before and after; if it fails afterwards the previous state is put back automatically, once. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'firewall_policy' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.

List zone-based firewall policies with hit counts and last-hit time, for audits.

Finds unused rules (zero hits), noisy rules and stale rules. The Integration API does not expose hit counts. Read-only: to change policies use the existing firewall tools.

Returns JSON: {"ok", "meta", "data": [{"name", "id", "index", "action", "enabled", "predefined", "hits", "last_hit", "logging", "source_zone", "destination_zone"}]}.

Search the UniFi OpenAPI spec for operations (undocumented controller / UniFi OS APIs plus the Integration API).

Use this first to find an operationId, then unifi_console_describe_operation, then unifi_console_call_operation. Does not call the console.

Returns JSON: {"ok": true, "total": int, "operations": [{"operation_id", "method", "path", "tag", "summary", "access"}], "next_offset": int|null}. By default only operations callable right now are shown.

Preview, then apply, the logging level (warn or debug) of the Network application's services: device, mgmt, sdn, system.

Two steps, always: call with confirm=false to get a read-only preview (the exact requests, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. With no fields, or setting_preference=auto, everything returns to the console's defaults (warn). The console does not report the current levels, so the preview has no before and the result cannot be read back (verified is null). Debug is chatty and fills storage: use it for diagnosis and put it back. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'logging_levels' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.

Preview, then apply, a change to a LAN/VLAN network. Tier C: a wrong change can cut DHCP, the VLAN and routing for a whole segment.

Two steps, always: confirm=false returns a read-only preview (before, after, diff, what uses the network, the clients on it, warnings, errors, a fingerprint); then call again with the same fields plus confirm=true, that fingerprint and an approval_note. A new network is created disabled. The network that holds the console, a switch, an access point or the gateway needs acknowledge_infrastructure=true for disabling, deleting, or changing its VLAN, subnet or DHCP server; a network used by an SSID or switch port cannot be deleted; disabling it or disruptive edits with clients connected need acknowledge_disconnect=true. After a change that touches an enabled network every connected device must still be connected and DNS must still work, otherwise the previous state is restored once. WAN, VPN, IPv6 and DHCP options are not offered. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'network' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.

Preview, then apply, a change to the console's network lists (port, address and domain lists used by firewall policies).

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, what uses the list, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. The list is re-read first, so a stale preview is refused. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'network_list' in UNIFI_CONSOLE_WRITE_ENTITIES. A list that firewall policies or traffic objects still use cannot be deleted, and editing one warns that the change takes effect for them at once. After applying, the list is read back and the result reports verified true/false, the diff, and the exact rollback call. Every write is journalled.

PoE budget for one switch plus the site's power supervisors (watchdogs that power-cycle ports).

Check this before diagnosing a PoE device that keeps rebooting: a supervisor with consecutive_failures above zero is power-cycling it. Returns JSON: {"ok", "data": {"poe_host": {...}, "power_supervisors": [...]}}.

Preview, then apply, a change to the console's port forwards (internet-to-LAN rules).

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. The rule is re-read first, so a stale preview is refused. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'port_forward' in UNIFI_CONSOLE_WRITE_ENTITIES. A new rule is created disabled; enabling one exposes a host to the internet and the preview says exactly what. After applying, the rule is read back and the result reports verified true/false, the diff, and the exact rollback call. Every write is journalled.

Preview, then apply, a change to the console's QoS rules (the dashboard's QoS widget; Traffic Management objects use unifi_console_traffic_object instead).

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. The rule is re-read first, so a stale preview is refused. A rule names a WAN or VPN link (wan_network), the clients it covers (source_clients, MAC addresses), the applications it matches (destination_apps, application ids), and an objective: LIMIT (download_limit / upload_limit in kbit/s, 10000 = 10 Mbit/s, with download_burst / upload_burst OFF, SHORT or LONG) or PRIORITIZE (no limits). Other source and destination types and schedules other than ALWAYS have not been captured and are not edited. A new rule starts switched off unless enabled=true; once enabled it takes effect at once. Use action enable or disable to switch one. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'qos_rule' in UNIFI_CONSOLE_WRITE_ENTITIES. The console only accepts the whole rule, so updates send all of it. After applying, the rule is read back and the result reports verified true/false, the diff, and the exact rollback call. Every write is journalled. Delete uses the console's batch-delete call.

Check the connection and report which account the server runs as, what it may do, and session facts.

Logs in if needed. Reports the controller version, the account's permissions, the session cookie's lifetime and whether the CSRF token has rotated, plus the server's safety settings. Use it first when a call fails with a permission or authentication error.

Returns JSON: {"ok", "controller": {...}, "account": {...}, "session": {...}, "server": {...}}.

Preview, then apply, a change to the gateway's Local DNS records (A, AAAA, CNAME, MX, SRV, TXT).

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. The record is re-read first, so a stale preview is refused. The gateway answers these names for every client, so the preview warns when a name is outside example.home (it replaces the public answer), refuses duplicates, the CNAME rule and names a client already publishes, and lists CNAME records that point at a record you change or remove. The console only accepts the whole record, so updates send all of it. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'static_dns' in UNIFI_CONSOLE_WRITE_ENTITIES. After applying, the record is read back and the result reports verified true/false, the diff, and the exact rollback call. Every write is journalled.

Generate a support file and (for the console) download it to disk.

The console bundle holds Network logs, remote syslog from every adopted device, configs and topology: the place to look when regular logs do not explain a fault (e.g. an STP problem visible only in device syslog). It contains secrets in plain text, so it is saved locally and never returned. Takes about a minute. Needs UNIFI_CONSOLE_ENABLE_WRITES=true, confirm=true, and Control Plane = Admin on the MCP account. scope='device' starts generation and reports status only.

Returns JSON: {"ok", "saved_file": {...}} (console) or {"ok", "data": {"status": ...}} (device).

Preview, then apply, a change to ONE port of ONE switch. Tier C: a wrong setting on an uplink, AP or console port can strand it.

Two steps, always: confirm=false returns a read-only preview (only that port's before/after, how the port is classified: uplink, infrastructure, client or unused, what is connected, warnings, errors, a fingerprint); then call again with the same fields plus confirm=true, that fingerprint and an approval_note. The console needs the whole port list on every save, so the tool sends every other port back exactly as read and checks afterwards that none of them changed. Risky fields (PoE, VLANs, isolation, BPDU guard, flow control, storm control) on uplink and infrastructure ports are refused unless acknowledge_infrastructure=true; a name change is always allowed. After a change every device that was connected must still be connected, otherwise the previous settings are put back automatically, once. Disabling a port, STP edge mode, port profiles and the other switch settings are not offered. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'switch_port' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.

Live per-port state for a switch: link, STP state/role, flaps, errors, PoE and optionally LLDP.

Trims the 1 MB+ device record to the useful port fields (any key starting stp_, poe_, lldp_ or containing error/drop/link_down is kept, so new firmware fields still appear). Read-only; secrets removed.

Returns JSON: {"ok", "data": {"name", "model", "version", "uplink", "stp": {...}, "ports": [...]}}.

Preview, then apply, a change to the console's remote syslog setting (where logs are sent and which categories).

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. Fields: enabled, netconsole_enabled, netconsole_host, netconsole_port, contents, log_all_contents, this_controller, this_controller_encrypted_only, debug. The host and port are also written to ip and port as the UI does. Changing or stopping the destination ends the feed to the current receiver, and the preview says so. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'syslog' in UNIFI_CONSOLE_WRITE_ENTITIES. The group is read back and verified. Every write is journalled.

Query the UniFi System Log (the Network app's 'System Log' page), with templates already filled in.

This is richer than the older event list: it records STP loops, BPDU guard, PoE and port faults, WAN failovers, security events and admin changes. Defaults to the last 24 hours at MEDIUM severity and above. Use critical_only=true for switching faults (NETWORK_LOOP_DETECTED_BY_STP, BPDU_GUARD_TRIGGERED, PORT_BROADCAST_STORM, ROGUE_DHCP_SERVER_DETECTED, ...).

Returns JSON: {"ok", "meta": {"total", "page", "total_pages"}, "data": [{"time", "severity", "category", "subcategory", "event", "target", "title", "message", "id"}]}, newest first.

Preview, then apply, a change to the console's traffic objects (Traffic Management: bandwidth limits and priority, schedules, internet blocking and routing for networks or clients).

Two steps, always: call with confirm=false to get a read-only preview (before, after, diff, warnings, a fingerprint); call again with the same fields plus confirm=true and that fingerprint to apply. The object is re-read first, so a stale preview is refused. Target networks (by name) or clients (by MAC). QoS: qos_enabled, qos_mode (LIMIT or PRIORITIZE), download_limit / upload_limit in kbit/s (10000 = 10 Mbit/s; 0 switches one off), download_burst / upload_burst (DISABLED, SHORT, LONG) and qos_schedule. block_internet (with block_schedule) cuts internet access for the targets, and route_* sends traffic out through another WAN or VPN client network; both need acknowledge_blocking / acknowledge_reroute when the object is switched on. A new object starts switched off unless enabled=true; once enabled it takes effect at once. App, domain and region matchers and the local-network block are not edited. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'traffic_object' in UNIFI_CONSOLE_WRITE_ENTITIES. The console only accepts the whole object, so updates send all of it. After applying, the object is read back and the result reports verified true/false, the diff, and the exact rollback call. Every write is journalled.

Preview, then apply, a change to the WAN network settings. Tier C: a wrong change can cut the internet.

Two steps, always: confirm=false returns a read-only preview (before, after, diff, warnings, errors, a fingerprint, and the safety-net check run now); then call again with the same fields plus confirm=true, that fingerprint and an approval_note. Only update exists. Connection identity (MAC override, WAN VLAN, connection type, IPv6 type, uplink identity) needs acknowledge_identity=true. The uplink password and everything not listed are not offered. Applying re-provisions the gateway (about 20 seconds). After the change the gateway must be connected again, all devices that were connected must still be, the WAN must report ok, an internet probe and DNS must work; otherwise the previous state is restored once, automatically. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'wan' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.

Preview, then apply, a change to a Wi-Fi network (SSID). Tier C: changes drop the clients on it.

Two steps, always: confirm=false returns a read-only preview (before, after, diff, the clients connected now, warnings, errors, a fingerprint); then call again with the same fields plus confirm=true, that fingerprint and an approval_note. A new SSID is created disabled. The passphrase is never an argument: pass passphrase_env, the name of a UNIFI_WIFI_* environment variable in the server's environment; it is write-only and is not read back, previewed or journalled. Changes that force clients to reconnect, and deletes, are refused while clients are connected unless acknowledge_disconnect=true; open security needs acknowledge_open=true. There is no automatic restore. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'wifi' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.