UniFi MCP Server
Provides management and analysis capabilities for UniFi Network and UniFi Protect infrastructure, including device and client management, site health, firewall and WLAN configuration, camera snapshots, and NVR monitoring.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@UniFi MCP Server Audit my UniFi network and flag any security or performance issues."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
UniFi MCP Server
mcp-name: io.github.mikeholownych/unifi-mcp
An MCP (Model Context Protocol) server that provides AI assistants like Claude with access to UniFi Network and Protect infrastructure management and analysis capabilities. It uses the native MCP SDK 2 MCPServer API (not FastMCP 3) and communicates over stdio by default.
Credits: This project started as a fork of gbassaragh/Unifi-mcp and has since evolved into a fully independent project. Thanks to @gbassaragh for the excellent starting point.
Improvements Over Upstream
Fixed local session authentication routing — in
UNIFI_MODE=local, requests now correctly use the traditional controller API (/proxy/network) with cookie + CSRF session auth. Upstream always routed through the Integration API regardless of mode.Mode-aware base URL resolution —
api_base_urlnow respects the configured auth mode instead of unconditionally returning the Integration API endpoint.Expanded test suite — 250+ passing tests covering configuration, MCP compatibility, runtime persistence, network client behavior, server tool registration, and Protect integrations.
Related MCP server: UniFi MCP Server
Features
UniFi Network
Device Management: List, restart, locate, and upgrade UniFi devices (APs, switches, routers)
Client Management: Monitor connected clients, block/unblock, view traffic statistics
Site Management: View site health, network configurations, VLANs, and wireless settings
Statistics & Monitoring: Events, alarms, speed tests, and DPI statistics
AI-Powered Insights: Network analysis, optimization recommendations, and troubleshooting
UniFi Protect
Camera Management: List cameras, view status, get live snapshots
System Monitoring: NVR status, camera health summaries
Accessories: Manage lights, sensors, chimes, and viewers
Liveviews: Access configured camera view layouts
Multi-Device Support
Configure multiple UniFi devices (gateways, NVRs, etc.)
Target specific devices by name — all network and Protect tools accept an optional
deviceparameterPer-device API keys: each configured device authenticates with its own key
Mix of Network and Protect services across devices
Events and Safe Automation
Normalize and durably deduplicate Network and Protect events in optional SQLite storage
Poll each configured source independently and report unsupported capabilities explicitly
Run only built-in interval jobs:
poll_events,retry_webhook_deliveries,capture_observations, andprune_runtime_dataDeliver filtered, signed HTTPS webhooks with bounded retries and dead-letter state
Keep persistence, background automation, and private webhook destinations disabled by default
Authentication Modes
Mode | Auth | Best for |
| Integration API key | Recommended default; broad read access |
| Username/password session | Full feature access: firewall rules, WLAN configs, site settings, events, alarms, DPI |
| api.ui.com key | Remote/cloud-managed controllers |
When API keys are used (Integration API), a subset of controller features is only available via legacy session auth (UNIFI_MODE=local): network events, alarms, DPI statistics, speed tests, WLAN configs, firewall rules, port profiles, and routing tables. Tools for these features return a clear error explaining how to enable them rather than failing silently. Insight tools degrade gracefully and report data limitations.
Note on local accounts: SSO/Ubiquiti-account admins protected by MFA cannot complete session login. Create a local admin on your console (Restrict to Local Access Only) for
UNIFI_MODE=local.
Agent Skills
Bundled skills (in skills/) teach agents proven workflows for this server — including
controller-specific gotchas (Network 10 removed endpoints, zone-pair rules, WPA3 transition).
Full documentation: See SKILLS.md for usage guide, expected results, troubleshooting, and how to request new functionality.
Quick reference
Skill | Type | Purpose |
| read-only | Full site audit: devices, clients, WiFi posture, firewall, structured report |
| read-only | Diagnose a misbehaving device: RF, roaming, blocking, IP layer |
| write-gated | Channel plan, widths, WPA3 transition, band steering — approval-gated |
| write-gated | Give a device a reserved IP + scoped zone-firewall access |
| read-only triage | "Internet is dead!" — plain-English outage diagnosis, ISP escalation script |
| read-only | "Who's on my WiFi?" — friendly inventory, intruder checks with randomized-MAC awareness |
| write-gated | Get any new gadget online: pairing pitfalls (2.4GHz/WPA3), naming, IP reservation |
| read-only | "Site won't load but ping works" — resolution vs connectivity split, forced-internal-DNS patterns |
| read-only+ | AirPrint/Cast broken across VLANs — mDNS reflection, IGMP/IPTV cautions |
| write-gated | Self-hosted service exposure incl. hairpin NAT, CGNAT detection, zone-policy pairing |
| write-gated | WireGuard/Teleport setup + failure ladder (handshake/MTU/zone-policies) |
| write-gated | Staged firmware updates: snapshot, canary, verify, stuck-device ladder |
| read-only | Slow far-room WiFi: wireless-uplink/hop diagnosis, wired-backhaul guidance |
| read-only+ | Threat alerts: false-positive vs real, suppression, IPS throughput cost |
| write-gated | What backups contain, migration rules of thumb, pre-migration snapshots |
| doc-writer | Persistent labeled topology (zones/VLANs/deps) that sharpens every other skill |
How skills work
Just describe your problem naturally — the agent matches your request to the right skill and follows its workflow:
"My internet is down" →
unifi-internet-downdiagnoses WAN, modem, gateway"Who's on my WiFi?" →
unifi-whos-homelists devices, flags unknowns"Audit my network" →
unifi-network-auditproduces a full health report"Set up my new TV" →
unifi-setup-new-deviceguides WiFi pairing
Write-gated skills (marked above) modify your network — they always ask approval before applying changes.
Skills for non-technical users avoid jargon, translate every technical term, and require confirmation before disruptive actions.
Install (per project): copy into .claude/skills/:
git clone https://github.com/mikeholownych/unifi-mcp.git
mkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/See SKILLS.md for full usage guide, expected results, troubleshooting, and how to request new functionality.
Skills reference MCP tools by their plain names (get_firewall_policies, …);
your MCP client prefixes them automatically.
Supported Hardware
UniFi Dream Machine (UDM, UDM-Pro, UDM-SE)
UniFi Cloud Gateway (UCG-Ultra, UCG-Fiber)
UniFi Network Video Recorder (UNVR, UNVR-Pro)
UniFi Network Application (self-hosted)
Traditional Cloud Key (Gen1, Gen2, Gen2+)
Limitations & Supported Versions
This server is built for operation on a trusted local network, talking to UniFi consoles by IP address. With that in mind:
TLS verification is disabled by default (
UNIFI_VERIFY_SSL=false). UniFi OS ships self-signed certificates, and controllers are reached by IP on the LAN, so certificate verification is expected to fail. EnableUNIFI_VERIFY_SSL=trueonly when your controller presents a CA-trusted certificate.No device configured at startup is allowed. The server boots and exposes all tools even before
UNIFI_*credentials are supplied (e.g. when deployed and configured via environment variables). Device-bound tool calls then return a clearNo device configurederror until a device is set.Scope enforcement applies to remote transports only. When running over Streamable HTTP, every
tools/callis gated by read/write/admin OIDC scopes, and startup fails if any tool is unclassified. Over stdio (local IPC) no auth is required — stdio is assumed to be a trusted local process.Integration API key limitations. A subset of controller features is only available via legacy session auth (
UNIFI_MODE=local): network events, alarms, DPI statistics, speed tests, WLAN/firewall configs, port profiles, and routing tables. Tools for these return a clear error explaining how to enable them.Tested against recent UniFi OS / Network / Protect. Newer controllers that removed legacy endpoints (e.g. UniFi Network 10 removed alarms/events endpoints) are handled by degrading gracefully rather than erroring.
Not a substitute for controller backups. Snapshots and reports are read-only exports; they do not configure or restore a controller.
Installation
Using uv (Recommended)
# Clone the repository
git clone https://github.com/mikeholownych/unifi-mcp.git
cd unifi-mcp
# Install dependencies
uv syncUsing pip
pip install -e .Configuration
Create a .env file in the project root (or set environment variables). See .env.example for all options.
UNIFI_CACHE_TTL controls the shared GET cache lifetime across client instances (default: 30
seconds). Mutation verification defaults to five fresh reads with exponential delays of 0.5, 1,
2, and 2 seconds. Tune this with UNIFI_MUTATION_VERIFY_ATTEMPTS,
UNIFI_MUTATION_VERIFY_INITIAL_DELAY, and UNIFI_MUTATION_VERIFY_MAX_DELAY when a controller
converges more slowly or quickly.
Optional Runtime Persistence
SQLite-backed runtime persistence is disabled by default. Enable it only when persistent runtime state is needed:
UNIFI_RUNTIME_ENABLED=trueBy default, the database is runtime.db under UNIFI_DATA_DIR. If UNIFI_DATA_DIR is not set, the server follows the XDG data convention: $XDG_DATA_HOME/unifi-mcp when XDG_DATA_HOME is an absolute path, otherwise ~/.local/share/unifi-mcp. The resulting default database is therefore $XDG_DATA_HOME/unifi-mcp/runtime.db or ~/.local/share/unifi-mcp/runtime.db.
Set an explicit data directory or database path when needed:
UNIFI_DATA_DIR=/var/lib/unifi-mcp
UNIFI_RUNTIME_DATABASE=/var/lib/unifi-mcp/runtime.dbUNIFI_DATA_DIR and UNIFI_RUNTIME_DATABASE must resolve to absolute paths. UNIFI_RUNTIME_DATABASE overrides the database derived from UNIFI_DATA_DIR.
Events, Schedules, and Webhooks
Runtime persistence enables event storage and management tools, but does not start background work. Enable the scheduler separately:
UNIFI_RUNTIME_ENABLED=true
UNIFI_AUTOMATION_ENABLED=trueEvent ingestion is capability-based polling, not a claim of universal UniFi push support:
Network event polling requires traditional local session auth with
UNIFI_MODE=local.Protect event polling requires a configured local
usernameandpasswordfor each Protect device.Integration API and cloud Network configurations are reported as unsupported for event polling.
Polling uses overlap plus durable source-key deduplication so timestamp boundaries do not create duplicate records.
Schedules can invoke only poll_events, retry_webhook_deliveries, capture_observations, or prune_runtime_data. Schedule and webhook mutations require confirm=true; arbitrary MCP tool names, commands, imports, and expressions are rejected.
Webhook destinations use HTTPS, do not follow redirects, and are resolved and checked before every attempt. Loopback, private, link-local, multicast, and reserved addresses are rejected unless UNIFI_WEBHOOK_ALLOW_PRIVATE=true. The dedicated webhook client retains certificate verification even when a UniFi controller uses a self-signed certificate.
Signing secrets never enter SQLite or MCP arguments. Set a secret in the server environment, then pass only its variable name as secret_env_name:
WEBHOOK_SECRET_AUTOMATION='replace-with-a-random-secret'Useful tools include get_event_polling_status, poll_events_now, list_runtime_events, create_interval_schedule, run_schedule_now, list_job_runs, create_webhook_destination, test_webhook_destination, and list_webhook_deliveries. Retryable jobs and webhook failures use bounded exponential backoff; exhausted deliveries enter dead_letter state.
Portable Snapshots and Reports
Portable snapshots are versioned, canonical JSON exports assembled from supported read APIs. They include source scope, explicit data limitations, Network/Protect inventory, networks, WLAN metadata, and firewall rule/policy metadata. Credentials, API keys, cookies, authorization headers, and WLAN passphrases are structurally excluded.
# Optional absolute override; defaults to <UNIFI_DATA_DIR>/exports
UNIFI_EXPORT_DIR=/var/lib/unifi-mcp/exportsExport tools accept a plain filename rather than an arbitrary path, reject traversal and symlinks, and atomically write files with 0600 permissions. export_portable_snapshot includes a SHA-256 content checksum; verify_snapshot detects malformed, truncated, or modified snapshots. export_network_report renders the same strict model as escaped standalone HTML or formula-safe CSV.
Native controller backup download and restore are intentionally reported as unavailable until controller-family endpoints and safe restore verification are validated. Portable snapshots support assessment and assisted reconstruction; they are not represented as restorable native controller backups.
History and Prometheus
With runtime persistence enabled, capture_observations_now stores bounded aggregate site health, device/client counts, traffic totals, and Protect camera health. It never stores per-client history or packet-flow telemetry. query_observation_trends returns bounded UTC buckets with present=false for missed collections rather than inventing interpolated values.
Prometheus support is not part of the base dependency set and starts no listener by default:
uv sync --extra observability
UNIFI_RUNTIME_ENABLED=true
UNIFI_PROMETHEUS_ENABLED=true
UNIFI_PROMETHEUS_HOST=127.0.0.1Metrics use fixed names without controller, site, client, MAC, IP, or SSID labels. Binding beyond loopback additionally requires UNIFI_PROMETHEUS_ALLOW_REMOTE=true and UNIFI_PROMETHEUS_BEARER_TOKEN_ENV naming an environment variable that contains the bearer token. The token value is read at request time and is never persisted.
Client Organization and QoS Previews
With runtime persistence enabled, clients can have multiple local tags and at most one local group. Membership is keyed by a controller/site-scoped SHA-256 value derived from the stable client MAC; raw MACs and mutable client names are not stored. Exact names and hostnames can be used as transient lookup hints, but ambiguous matches are rejected and the exact MAC must be supplied. Tags and groups survive client renames and do not change controller configuration.
Organization mutations require confirm=true. Use set_client_tags, create_client_group, assign_client_group, list_client_groups, and list_clients_by_organization to manage or query local metadata.
plan_client_qos_policy persists a one-hour deterministic target snapshot selected by one client, tag, or group. The target ledger contains only scoped one-way client keys and supports future resumable per-target apply state. This release has no validated controller QoS adapter: get_client_qos_capabilities reports that limitation, and apply_client_qos_policy returns without making a controller mutation. Local tags never imply a QoS policy.
Trusted Plugins
Plugins are disabled unless their Python entry-point name is explicitly listed in UNIFI_PLUGIN_ALLOWLIST. They execute as trusted local code in the server process and are not sandboxed. Required plugins must also be allowlisted and are listed in UNIFI_PLUGIN_REQUIRED; missing, incompatible, duplicate, or failed required plugins stop startup. Optional failures are isolated and visible through get_plugin_status.
Plugins use API version 1 and the unifi_mcp.plugins entry-point group:
[project.entry-points."unifi_mcp.plugins"]
example = "example_package.plugin:plugin"The loaded object declares api_version = 1 and implements register(registry). The registry supports register_tool with an explicit read, write, or admin scope, plus named collectors, JobDefinition jobs, notification sinks, and byte-returning report renderers. Plugin names cannot shadow core tools or jobs.
Streamable HTTP and OIDC
Stdio remains the default local process transport and requires no identity-provider configuration. Remote MCP starts only when UNIFI_TRANSPORT=streamable-http; install the declared authentication capability with uv sync --extra oidc and provide complete OIDC settings:
UNIFI_TRANSPORT=streamable-http
UNIFI_HTTP_HOST=127.0.0.1
UNIFI_HTTP_PORT=8000
UNIFI_HTTP_PATH=/mcp
UNIFI_HTTP_PUBLIC_URL=https://mcp.example.com/mcp
UNIFI_OIDC_ISSUER=https://identity.example.com
UNIFI_OIDC_AUDIENCE=unifi-mcp
UNIFI_OIDC_ALGORITHMS=RS256Discovery and JWKS data are fetched over HTTPS with bounded timeouts, cached for five minutes by default, and refreshed once for an unknown signing key. Tokens are validated locally for allowed asymmetric algorithm, signature, issuer, audience, expiry, subject, and scopes. Authorization headers, tokens, claims, and signing keys are not logged or persisted.
All HTTP tool calls require UNIFI_OIDC_READ_SCOPE (unifi:read by default). Mutations additionally require UNIFI_OIDC_WRITE_SCOPE; runtime administration and plugin status require UNIFI_OIDC_ADMIN_SCOPE. Existing confirm=true gates still apply. Non-loopback binding additionally requires UNIFI_HTTP_ALLOW_REMOTE=true; production TLS should terminate at the declared HTTPS public URL.
Multi-Device Configuration (Recommended)
Configure multiple UniFi devices with different services:
UNIFI_DEVICES='[
{
"name": "main-gateway",
"url": "https://192.168.1.1",
"api_key": "your-gateway-api-key",
"services": ["network"],
"site": "default"
},
{
"name": "nvr",
"url": "https://192.168.1.2",
"api_key": "your-nvr-api-key",
"services": ["network", "protect"],
"site": "default"
}
]'
UNIFI_VERIFY_SSL=falseDevice configuration fields:
Field | Description | Default |
| Friendly name for targeting the device | (required) |
| Base URL of the UniFi device | (required) |
| API key from UniFi OS Control Plane | (required) |
| Array: |
|
| Site name for network operations |
|
| Verify SSL certificates |
|
| Username for Protect events (optional) |
|
| Password for Protect events (optional) |
|
Note: The username and password fields are only required for Protect event tools (motion events, smart detections). Basic camera operations work with just the API key.
To create an API key:
Log into your UniFi controller
Go to Settings → Control Plane → API
Create a new API key with appropriate permissions
Legacy Single-Device Configuration
For backwards compatibility, single-device configuration is still supported:
UNIFI_MODE=local_api_key
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_CLOUD_API_KEY=your-api-key
UNIFI_SITE=default
UNIFI_VERIFY_SSL=falseLocal Session Auth (Traditional)
For full-feature access with username/password authentication:
UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=local-admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=falseCloud API (api.ui.com)
For Ubiquiti Cloud API access:
UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-keyGet your API key from unifi.ui.com → API section.
Usage with Claude Desktop
Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json on Linux or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"unifi": {
"command": "uv",
"args": ["run", "--directory", "/path/to/unifi-mcp", "python", "-m", "unifi_mcp.server"],
"env": {
"UNIFI_DEVICES": "[{\"name\":\"gateway\",\"url\":\"https://192.168.1.1\",\"api_key\":\"your-key\",\"services\":[\"network\"]},{\"name\":\"nvr\",\"url\":\"https://192.168.1.2\",\"api_key\":\"your-key\",\"services\":[\"network\",\"protect\"]}]",
"UNIFI_VERIFY_SSL": "false"
}
}
}
}Usage with Claude Code / opencode
# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.serverOr in opencode.json:
{
"mcp": {
"unifi": {
"type": "local",
"command": ["/path/to/unifi-mcp/.venv/bin/python", "-m", "unifi_mcp.server"],
"enabled": true
}
}
}Available Tools
Server Health
get_server_health- Report the server version, stdio transport, configured service counts, and optional persistence status. The response deliberately omits credentials, controller addresses, device names, and database paths.
Multi-Device Management
list_unifi_devices- List all configured UniFi devices and their services
Device Management
list_devices- List all UniFi network devicesget_device_details- Get detailed device informationrestart_device- Restart a devicelocate_device- Blink LED to locate deviceget_device_stats- Get performance statisticsupgrade_device- Upgrade firmwareprovision_device- Force re-provisionget_device_ports- List switch/gateway port configuration and link stateset_device_port- Configure one port; requiresconfirm=trueand verifies controller read-back
Client Management
list_clients- List connected clientslist_all_clients- List all known clients (including offline)get_client_details- Get client detailsblock_client/unblock_client- Block/unblock clientskick_client- Disconnect a clientforget_client- Remove from known clientsget_client_traffic- Get traffic statisticsreserve_client_ip- Reserve IP via DHCP reservationget_client_organization/set_client_tags- Read or replace durable local tagscreate_client_group/delete_client_group- Manage local-only groupsassign_client_group/list_client_groups- Manage and inspect single-group membershiplist_clients_by_organization- Resolve deterministic tag or group target setsget_client_qos_capabilities- Report validated controller QoS supportplan_client_qos_policy/apply_client_qos_policy- Preview QoS targets and apply only when a validated adapter exists
Site Management
list_sites- List all sitesget_site_health- Get site health statusget_site_settings- Get site settingsget_sysinfo- Get system informationget_networks- Get network/VLAN configsget_wlans- Get wireless network configsget_port_profiles- Get switch port profilesget_firewall_rules- Get legacy firewall rulesget_firewall_policies- Get zone-based firewall policies (UniFi Network 9+)get_routing_table- Get routing tableget_port_forwards- Get port forwarding rulescreate_port_forward/delete_port_forward- Manage port forwards
Configuration Management (writes)
create_network/update_network/delete_network- Manage networks and VLANs; each requiresconfirm=trueand verifies controller read-backcreate_wlan/update_wlan/delete_wlan- Manage wireless networkscreate_firewall_policy/set_firewall_policy_enabled/delete_firewall_policy- Manage zone-based firewall policiesexport_camera_clip- Export an MP4 beneathUNIFI_EXPORT_DIR; requiresconfirm=trueget_all_sites_health- Health overview across all sites
Write tools that remove data or cause disruption are confirm-gated or flagged destructive via MCP annotations.
Statistics & Monitoring
get_network_health- Overall network healthget_recent_events- Recent eventsget_alarms- Active alarmsarchive_all_alarms- Archive all alarmsrun_speed_test- Start speed testget_speed_test_status- Get speed test resultsget_dpi_stats- DPI statisticsget_traffic_summary- Traffic summary
AI Insight Tools
analyze_network_issues- Comprehensive issue analysisget_optimization_recommendations- Configuration recommendationsget_client_experience_report- Client quality metricsget_device_health_summary- Device health overviewget_traffic_analysis- Traffic pattern analysisget_all_sites_health- Health overview across all sites
Multi-Site Orchestration
get_global_inventory- Unified device inventory across all controllersget_global_health- Aggregated health report across all controllersget_global_client_summary- Client counts, top talkers, blocked clients across all controllerstroubleshoot_client- Deep-dive client troubleshooting
UniFi Protect
list_cameras- List all cameras with connection statusget_camera_details- Get detailed camera informationget_camera_snapshot- Get live snapshot (base64 JPEG)get_protect_system_info- Get NVR system informationget_camera_health_summary- Camera health overview with issuesget_liveviews- Get configured liveview layoutsget_protect_accessories- List lights, sensors, chimes, viewers
UniFi Protect Events (require username/password)
get_motion_events- Get recent motion eventsget_smart_detections- Get smart detection events (person, vehicle, animal, package)get_protect_event_summary- Summary of all events by typeget_recent_protect_activity- Quick overview of recent activity
Example Conversations
After connecting the MCP server, you can ask Claude:
Network Management
"List all my UniFi devices"
"What's the current network health?"
"Analyze my network for any issues"
"What optimization recommendations do you have?"
"Show me client experience metrics"
"Troubleshoot the client with MAC aa:bb:cc:dd:ee:ff"
"Which clients are using the most bandwidth?"
"Are there any devices that need firmware updates?"
"Show me the recent network events"
"Run a speed test"
UniFi Protect
"List all my cameras"
"Show me the camera health summary"
"Get a snapshot from the Front Door camera"
"What's the status of my NVR?"
"Are any cameras disconnected?"
"Show me the protect accessories"
Protect Events (requires credentials)
"Show me recent motion events"
"What smart detections happened in the last 24 hours?"
"Were there any person detections today?"
"Give me an event summary for the past week"
"Show recent activity from the Front Door camera"
Multi-Device
"List my configured UniFi devices"
"Show cameras on my NVR"
"Get network health from the main gateway"
Development
Running Tests
uv run pytestCode Formatting
uv run ruff check .
uv run ruff format .Docker
docker build -t unifi-mcp .
docker run -i --rm --env-file .env unifi-mcpTo enable optional runtime persistence, mount a named volume at the image's writable /data directory:
docker run -i --rm \
--env-file .env \
--env UNIFI_RUNTIME_ENABLED=true \
--env UNIFI_DATA_DIR=/data \
--volume unifi-mcp-data:/data \
unifi-mcp--rm removes the stopped container, but the unifi-mcp-data named volume remains and preserves /data/runtime.db for subsequent runs.
Requesting new functionality
New skills: Open an issue with
[Skill]prefix — describe the problem, workflow, and expected outputModify skills: Open an issue with
[Skill: skill-name]prefix — what's missing or brokenNew tools: Open an issue with
[Tool]prefix — include the UniFi API endpoint and expected format
See SKILLS.md for detailed contribution guidelines.
See CHANGELOG.md for release history and CONTRIBUTING.md to contribute.
Security Notes
Credentials are passed via environment variables — never commit
.envTLS verification is disabled by default (
UNIFI_VERIFY_SSL=false) because the server is designed to run on a trusted LAN against UniFi consoles reached by IP with self-signed certificates. Enable it only with a CA-trusted certificate.Over stdio (local IPC), no authentication is required — the transport is assumed to be a trusted local process. Over Streamable HTTP, all tool calls require a valid OIDC token with the appropriate read/write/admin scope, enforced server-side.
The server exposes both read and write tools
Disruptive or destructive tools are annotated and/or explicitly confirm-gated where implemented; MCP clients decide how to present or honor annotations
Especially dangerous operations such as factory reset remain unexposed
API keys should be kept secure and rotated periodically
License
MIT License
Contributing
Contributions are welcome! Please open an issue or submit a pull request.
Available Tools
111 toolsanalyze_network_issuesARead-only
Analyze a site and return a structured report of potential issues.
Read-only operation: it aggregates device health, client connection problems, interference, firmware status, and recent alarms into an AI-friendly summary of what may be wrong. Use get_alarms for the raw active-alarm list, get_device_health_summary for device-only status, or get_optimization_recommendations when you want improvement suggestions rather than a fault report.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
apply_client_qos_policyADestructive
Apply a validated QoS preview when a supported adapter exists. Requires confirmation.
Mutating operation: loads the plan referenced by plan_token and attempts to activate it. In the current release no validated adapter exists, so no controller mutation is performed (mutation_attempted=false); the call records the attempt. Returns success=false unless confirm=true. Use plan_client_qos_policy first to obtain a plan_token.
Args: plan_token: Token returned by plan_client_qos_policy identifying the plan. confirm: Must be True to attempt application; without it the call is a no-op. Defaults to False.
Inputs: plan_token (required), confirm.
archive_all_alarmsAIdempotent
Acknowledge and archive every active alarm on a site.
Non-destructive state change: it marks open alarms as archived so they no longer show in get_alarms; no device configuration is modified. Use get_alarms first to review what will be cleared; prefer analyze_network_issues when you want findings without clearing alarm state.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
assign_client_groupAIdempotent
Assign or unassign one local client group. Requires confirm=true.
Mutating operation: sets the client's single local group membership (local_only) to the given group, or clears it when group is null. Does not mutate the controller. Returns success=false unless confirm=true. Use set_client_tags for tags, or list_clients_by_organization to find clients in a group.
Args: identity: Client MAC, IP, hostname, or alias to resolve to a known client. group: Group name to assign, or null/None to unassign the current group. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default. confirm: Must be True to change membership; without it the call is a no-op. Defaults to False.
Inputs: group (required), identity (required), site, device, +1 more.
block_clientAIdempotent
Block a client from accessing the network by MAC address.
Mutating operation: the block is applied immediately and persists in the controller's firewall/blocklist. Use unblock_client to restore access, or kick_client to drop the connection without a persistent block.
Args: mac: Client MAC address to target. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
capture_observations_nowAIdempotent
Capture a bounded batch of aggregate UniFi health observations immediately.
Mutating operation: collects current health observations and persists them into the observation store right away, then refreshes cached metrics. Returns the number of inserted observations and any scope limitations. Use before query_observation_trends to ensure recent data, or rely on scheduled capture otherwise.
Inputs: no named parameters.
create_client_groupADestructive
Create a controller-independent local client group. Requires confirm=true.
Mutating operation: persists a new empty local group (local_only) scoped to the controller/site; it does not create anything on the UniFi controller. Returns success=false unless confirm=true. Use assign_client_group to add members, or list_client_groups to see existing groups.
Args: name: Unique group name to create. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default. confirm: Must be True to create the group; without it the call is a no-op. Defaults to False.
Inputs: name (required), site, device, confirm.
create_firewall_policyA
Create a zone-based firewall policy (UniFi Network 9+).
Mutating operation: applied immediately and persisted on the UniFi console. Action is ALLOW, BLOCK, or REJECT across the src_zone_id to dst_zone_id pair. Lower index evaluates earlier. A controller-generated "(Return)" companion rule is typically added. Requires zone ids from get_firewall_policies; review there first.
Args: name: Policy name (used for display and zone inference). action: Packet decision — "ALLOW", "BLOCK", or "REJECT". src_zone_id: Source zone id (from get_firewall_policies). dst_zone_id: Destination zone id (from get_firewall_policies). protocol: Protocol selector — "all", "tcp", "udp", "tcp_udp", "icmp", "igmp", or "icmpv6". description: Optional human-readable description. client_macs: Restrict the source to these client MAC addresses. index: Rule order index; lower values evaluate earlier. Omit for auto-order. enabled: Create the policy enabled. Defaults to True. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: name (required), action (required), dst_zone_id (required), src_zone_id (required), +7 more.
create_firewall_ruleADestructive
Create a legacy firewall rule (UniFi Network <9 or traditional API).
Mutating operation: applied immediately and persisted on the controller. For zone-based policies (Network 9+), prefer create_firewall_policy. Review existing rules with get_firewall_rules first.
Args: name: Unique rule name action: Action — "accept", "drop", or "reject" protocol: Protocol — "tcp", "udp", "icmp", "all", or IANA number dst_port: Destination port or range (e.g., "80", "80-443") src_zone: Source zone ID (from get_firewall_policies) dst_zone: Destination zone ID src_port: Source port or range logging: Enable logging for matches enabled: Whether rule is active on creation. Defaults to True. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific console; omit for default.
Returns: Created firewall rule configuration
Inputs: name (required), action (required), protocol (required), site, +7 more.
create_interval_scheduleADestructive
Create an allowlisted recurring job. Requires confirm=true.
Mutating operation: persists a new interval schedule that runs job_name with the given arguments every interval_seconds. Returns success=false unless confirm=true. The job must be on the allowlist. Use set_schedule_enabled to pause it, or delete_schedule to remove it.
Args: name: Unique schedule identifier. job_name: Allowlisted job to run on the interval. interval_seconds: Recurrence period between runs, in seconds. arguments: Optional keyword arguments passed to the job on each run. confirm: Must be True to create the schedule; without it the call is a no-op. Defaults to False.
Inputs: name (required), job_name (required), interval_seconds (required), confirm, +1 more.
create_networkADestructive
Create a new network/VLAN segment on the gateway (corporate by default).
Mutating operation: applied immediately and persisted on the UniFi console. Provide subnet in CIDR form and an optional VLAN id to tag the segment; enable DHCP by supplying both dhcp_start and dhcp_stop. Requires confirm=true because routing/VLAN/DHCP changes can disrupt connectivity. Inspect with get_networks; reverse with delete_network.
Args: name: Network name (e.g. "IoT"). subnet: Subnet in CIDR form (e.g. "192.168.50.1/24"); omit for unrouted. vlan: VLAN id (1-4094) for a tagged segment; omit for untagged. purpose: Segment type — "corporate", "guest", or "wan". Defaults to "corporate". domain_name: DNS domain name advertised to clients (e.g. "example.local"). dhcp_start: DHCP pool start IP; supply with dhcp_stop to enable DHCP. dhcp_stop: DHCP pool end IP; supply with dhcp_start to enable DHCP. dhcp_lease_time: DHCP lease duration in seconds (default 86400). site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default. confirm: Safety gate: must be True to create. Defaults to False.
Inputs: name (required), site, vlan, device, +7 more.
create_port_forwardADestructive
Create a port-forwarding rule that opens an external WAN port and maps it to an internal host/port.
Mutating operation: applied immediately and persisted on the UniFi console. Review existing rules with get_port_forwards first; remove with delete_port_forward. Prefer create_firewall_policy for zone-based/stateful filtering.
Args: name: Unique rule identifier used to find/delete the rule later. dst_port: Internal destination port (1-65535) on the target host. fwd_ip: LAN IP of the internal host receiving forwarded traffic. fwd_port: External listening port (1-65535) on the WAN. proto: IP protocol to forward — "tcp", "udp", or "both". enabled: Whether active on creation. Defaults to True. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: name (required), fwd_ip (required), dst_port (required), fwd_port (required), +4 more.
create_webhook_destinationADestructive
Create a filtered outbound webhook. Requires confirm=true.
Mutating operation: persists a new outbound webhook destination posting to url, optionally signing with a secret from secret_env_name and limited to categories. Returns success=false unless confirm=true. Use set_webhook_destination_enabled to pause it, or delete_webhook_destination to remove it.
Args: name: Unique destination identifier. url: Endpoint that receives webhook payloads. secret_env_name: Optional name of an env var holding the signing secret. categories: Optional list of event categories to send; empty sends all. confirm: Must be True to create the destination; without it the call is a no-op. Defaults to False.
Inputs: url (required), name (required), confirm, categories, +1 more.
create_wlanADestructive
Create a wireless network (SSID) with WPA2/WPA3 transition security by default.
Mutating operation: applied immediately and persisted on the UniFi console. Passphrase must be 8-63 characters. WPA2/WPA3 transition is enabled unless wpa3_transition is False, keeping WPA2 for legacy clients. Attach to a VLAN via network_conf_id, or mark is_guest for an isolated guest SSID. Inspect with get_wlans.
Args: name: SSID broadcast name. passphrase: WiFi password, 8-63 characters. network_conf_id: Network id to attach the SSID to; omit for the default LAN. wpa3_transition: Use WPA2/WPA3 transition mode. Defaults to True. hide_ssid: Broadcast the SSID hidden when True. Defaults to False. is_guest: Mark the SSID as an isolated guest network. Defaults to False. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: name (required), passphrase (required), site, device, +4 more.
delete_client_groupADestructive
Delete a local group and its memberships. Requires confirm=true.
Mutating operation: removes the local group (local_only) and detaches its members; it does not touch the UniFi controller. Returns success=false unless confirm=true. Recreate with create_client_group if needed.
Args: name: Name of the local group to delete. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default. confirm: Must be True to delete the group; without it the call is a no-op. Defaults to False.
Inputs: name (required), site, device, confirm.
delete_firewall_policyADestructive
Delete a zone-based firewall policy.
Mutating operation: removed immediately and persisted on the UniFi console. Requires confirm=true because removing a policy changes traffic flow. Predefined controller policies are refused. Target by id from get_firewall_policies.
Args: policy_id: Policy id to delete (from get_firewall_policies). confirm: Safety gate: must be True to delete. Defaults to False. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: policy_id (required), site, device, confirm.
delete_firewall_ruleADestructive
Delete a legacy firewall rule. Requires confirm=True.
Mutating operation: permanently removes the rule from the controller.
Args: rule_id: Firewall rule ID (from get_firewall_rules) confirm: Must be True to actually delete site: Site to operate on. Defaults to "default". device: Optional console name to target a specific console; omit for default.
Returns: Deletion status
Inputs: rule_id (required), site, device, confirm.
delete_networkADestructive
Delete a network/VLAN by name or ID.
Mutating operation: removed immediately and persisted on the UniFi console. Requires confirm=true because deleting a network can drop clients and routes that depend on it. List networks with get_networks first to confirm the target.
Args: name: Network name or record id to delete. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default. confirm: Safety gate: must be True to delete. Defaults to False.
Inputs: name (required), site, device, confirm.
delete_port_forwardADestructive
Delete a port forwarding rule.
Mutating operation: removed immediately and persisted on the UniFi console. Requires confirm=true because removing a forward closes external access. Target by rule id from get_port_forwards.
Args: rule_id: Port forward rule id to delete (from get_port_forwards). confirm: Safety gate: must be True to delete. Defaults to False. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: rule_id (required), site, device, confirm.
delete_scheduleADestructive
Delete a non-running schedule. Requires confirm=true.
Mutating operation: removes the identified schedule from the store. Returns success=false unless confirm=true. Use create_interval_schedule to add one, or set_schedule_enabled to pause instead of delete.
Args: schedule_id: Identifier of the schedule to delete. confirm: Must be True to delete the schedule; without it the call is a no-op. Defaults to False.
Inputs: schedule_id (required), confirm.
delete_webhook_destinationADestructive
Delete a webhook destination and queued deliveries. Requires confirm=true.
Mutating operation: removes the identified webhook destination and its queued deliveries from the store. Returns success=false unless confirm=true. Use create_webhook_destination to add one.
Args: destination_id: Identifier of the webhook destination to delete. confirm: Must be True to delete the destination; without it the call is a no-op. Defaults to False.
Inputs: destination_id (required), confirm.
delete_wlanADestructive
Delete a wireless network (SSID).
Mutating operation: removed immediately and persisted on the UniFi console. Requires confirm=true because deleting an SSID disconnects its clients. Resolve the target by ID or name and review get_wlans first.
Args: wlan: WLAN id or SSID name to delete. confirm: Safety gate: must be True to delete. Defaults to False. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: wlan (required), site, device, confirm.
export_camera_clipADestructive
Export a UniFi Protect recording clip as an MP4 file written to local disk.
Mutating, file-writing operation: it resolves the camera (by id or name), fetches the recording for the requested time range, and writes an MP4 file into the server's confined export directory (the path is validated against that directory, so output_path must not escape it). Requires Protect username/password credentials configured for the console. The write is a no-op until confirm is set to true, at which point it returns the written file path and size in bytes. Use get_camera_snapshot for a single still image instead of a time-ranged clip.
Args: camera: Protect camera identifier or name to export footage from. start_ts: Clip start time as a Unix epoch timestamp (seconds). end_ts: Clip end time as a Unix epoch timestamp (seconds); must be after start_ts. output_path: Destination filename (or path relative to the export directory); it is confined to the server's export directory. device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device. confirm: Safety confirmation required for this file-writing operation; the export returns a failure message until set to true.
Inputs: camera (required), end_ts (required), start_ts (required), output_path (required), +2 more.
export_network_reportADestructive
Export an HTML or CSV report rendered from the portable snapshot model.
Mutating operation: writes a local report file immediately, persisted in the export directory. The call is rejected without writing unless confirm=true. Format must be "html" or "csv" and filename must end with the matching extension; plugins may register additional formats. Prefer export_portable_snapshot for the raw machine-readable model.
Args: filename: Output report file name inside the confined export directory; must end with the chosen format extension (e.g. .html, .csv). format: Report renderer to use — "html" or "csv" (plugins may register additional formats). confirm: Safety confirmation. Must be True to actually write; otherwise returns a rejection message.
Inputs: format (required), filename (required), confirm.
export_portable_snapshotADestructive
Export a deterministic secret-free JSON snapshot to a local confined file.
Mutating operation: writes a local file immediately, persisted in the export directory. Returns the filename, size, schema version, and a content SHA-256 checksum for later verification with verify_snapshot. The call is rejected without writing unless confirm=true. Use export_network_report for human-readable HTML/CSV instead of the raw JSON model.
Args: filename: Target file name written inside the confined export directory (no path traversal). confirm: Safety confirmation. Must be True to actually write; otherwise returns a rejection message.
Inputs: filename (required), confirm.
forget_clientADestructive
Remove a client from the controller's known-clients list.
Destructive operation: deletes the client's stored identity and history; the client can still reappear on reconnect. Use kick_client to drop a session without deletion, or block_client to deny access persistently.
Args: mac: Client MAC address to target. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
get_alarmsARead-only
Return the currently active alarms (faults and warnings) for a site.
Read-only operation: it lists unacknowledged/active alarms with severity and message so you can see what needs attention. Use get_recent_events for the broad event feed including non-alarm activity; clear them with archive_all_alarms once handled, or use analyze_network_issues for a consolidated interpretation of alarms and health.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_all_sites_healthARead-only
Return a health overview for every site managed by one UniFi console.
Read-only operation: it walks each site on the targeted console and returns a compact health snapshot per site (status, score, and key counts). Unlike get_global_health, this stays within a single console; unlike get_site_health, it covers all sites at once rather than one. Use get_global_health when you need cross-console aggregation; prefer get_site_health when you want full per-subsystem detail for a single named site.
Args: device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: device.
get_camera_detailsARead-only
Get the full configuration and runtime record for one Protect camera.
Read-only operation: it returns the camera's model, firmware, resolution, recording mode, privacy/IR state, connection state, and live statistics. The camera is resolved by ID first and then by name, so either form is accepted. Use list_cameras first to find the camera_id; use get_camera_snapshot to capture an image, or get_camera_health_summary for a connectivity-only view.
Args: camera_id: Protect camera identifier or name to look up. device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: camera_id (required), device.
get_camera_health_summaryARead-only
Summarize the connectivity and health of all cameras on one Protect console.
Read-only operation: it partitions cameras into connected and disconnected sets, returns an overall status of "healthy" or "degraded", lists each disconnected camera as a critical issue, and offers remediation recommendations. Use this for a fleet-wide connectivity check; use list_cameras for the full per-camera detail or get_camera_details for one camera's complete record.
Args: device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: device.
get_camera_snapshotARead-only
Capture a still image from a connected Protect camera as a base64 JPEG.
Read-only operation: it requests a live frame from the camera and returns it as a base64-encoded JPEG plus camera name and id. If width and/or height are provided the image is resized to those pixel dimensions; if omitted the camera's native resolution is returned. A camera that is not in the CONNECTED state returns a success=false result rather than an image. Use get_camera_details to confirm the camera is online before calling.
Args: camera_id: Protect camera identifier or name to capture from. device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device. width: Optional target pixel width for the snapshot; native width if unset. height: Optional target pixel height for the snapshot; native height if unset.
Inputs: camera_id (required), width, device, height.
get_client_detailsARead-only
Get the full device record for one client by MAC address.
Read-only operation: returns the client's identity, connection state, IP, signal/AP association, and history. Deeper than list_clients/list_all_clients, which return summarized rows only.
Args: mac: Client MAC address to target. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
get_client_experience_reportARead-only
Generate a client experience report with connection-quality metrics for a site.
Read-only operation: it summarizes signal-strength distribution, roaming stats, failed connections, and problematic clients across the site. Use troubleshoot_client for a deep dive on one specific client, or get_device_health_summary for the infrastructure view rather than client-side.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_client_organizationARead-only
Get durable local tags and group membership for one known client.
Read-only operation: resolves the client by identity, then returns its persisted local organization record (tags and group membership). This data is local to the server (local_only) and does not mutate the controller. Use set_client_tags or assign_client_group to change it.
Args: identity: Client MAC, IP, hostname, or alias to resolve to a known client. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: identity (required), site, device.
get_client_qos_capabilitiesARead-only
Describe validated controller QoS mutation capabilities.
Read-only operation: reports whether a validated controller QoS adapter is available for the targeted device. Previews created by plan_client_qos_policy are always local; apply_client_qos_policy performs no controller mutation in the current release. Use this before planning a policy to set expectations.
Args: device: Optional device name to target a specific console; omit for default.
Inputs: device.
get_client_trafficARead-only
Get traffic statistics (rx/tx, throughput) for one client by MAC address.
Read-only operation: returns the client's cumulative and recent traffic counters. Use get_client_details for identity/connection state, or get_traffic_summary for site-wide traffic rather than a single client.
Args: mac: Client MAC address to target. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
get_device_detailsARead-only
Get detailed configuration and runtime record for one UniFi device.
Read-only operation: returns the device's ports, radios, uplink, system stats, temperatures, and traffic counters. The device is resolved by MAC first, then by name. Use list_devices to find the MAC; use get_device_stats for a metrics-only view without the full config dump.
Args: mac: Device MAC address (case-insensitive; aa:bb:cc:dd:ee:ff or aabbccddeeff). site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
get_device_health_summaryARead-only
Summarize device health across all APs, switches, and routers at a site.
Read-only operation: it reports uptime, load, memory, temperature, firmware versions, and devices needing attention. Use get_site_health or get_network_health for overall/site status, analyze_network_issues for issues folded into a report, or get_client_experience_report for the client perspective.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_device_portsARead-only
List the switch/gateway ports on a device with link and VLAN details.
Read-only operation: returns each port's index, name, media (GE/SFP), link state, speed, native network (VLAN) ID, PoE mode, forward setting, and the last connected peer MAC/IP where known. Use this to find the port_idx and current values before calling set_device_port.
Args: mac: Device MAC address (case-insensitive; aa:bb:cc:dd:ee:ff or aabbccddeeff). site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
get_device_statsARead-only
Get performance and traffic statistics for one UniFi device.
Read-only operation: returns CPU/memory load, temperatures, fan level, client counts (user/guest), traffic totals, and AP radio stats where applicable. Use get_device_details for the full config record instead of metrics, or list_devices for a lightweight summary.
Args: mac: Device MAC address (case-insensitive; aa:bb:cc:dd:ee:ff or aabbccddeeff). site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
get_dpi_statsARead-only
Return Deep Packet Inspection application-breakdown statistics for a site.
Read-only operation: it ranks traffic by detected application/category so you can see what protocols and apps dominate usage. Use get_traffic_summary for a lighter volume-only overview, get_traffic_analysis for time-windowed trends and top talkers, or get_client_traffic for a single client's DPI view.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_event_polling_statusARead-only
List event source capabilities and background polling state.
Read-only operation: returns each known event source with its capabilities and whether background polling is enabled. Use this to discover source names for poll_events_now, or list_runtime_events to read stored events.
Inputs: no named parameters.
get_firewall_policiesARead-only
Get zone-based firewall policies (UniFi Network 9+).
Read-only operation: returns each policy's name, action, protocol, index order, and source/destination zone ids. Policies are evaluated in index order; predefined "(Return)" companions appear alongside custom rules. Use create_firewall_policy to add one, or set_firewall_policy_enabled / delete_firewall_policy to manage it.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
get_firewall_rulesARead-only
Get legacy firewall rule configurations for a site.
Read-only operation: returns each rule's name, action, protocol, port, ruleset, and firewall-group bindings. Modern controllers use zone-based policies instead — see get_firewall_policies. Use create_firewall_policy for zone-based filtering.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
get_global_client_summaryARead-only
Summarize connected clients across every configured network console.
Read-only operation: it aggregates active clients from each network-enabled device and computes totals (wireless/wired/blocked), the top 10 talkers by usage, and a per-device client count. Use this for fleet-wide client visibility; use get_global_inventory for the device roster, get_global_health for subsystem health, or list_clients on a single console for the full per-client detail.
Returns: Dict with total_clients, wireless/wired/blocked counts, top_talkers, per_device counts, and an errors list when a console fails.
Inputs: no named parameters.
get_global_healthARead-only
Aggregate site health across every configured network console into one report.
Read-only operation: it collects per-subsystem site health (WAN/LAN/WLAN status, health score, and device/user counts) from each network-enabled device and folds them into a unified view with an overall "healthy" or "degraded" verdict. Use this for a single fleet-wide health check; use get_global_inventory for the device roster, get_global_client_summary for client counts, or get_site_health on a single console for full subsystem detail.
Returns: Dict with overall_status, device_count, a per-device subsystems breakdown, and an errors list when a console fails.
Inputs: no named parameters.
get_global_inventoryARead-only
Aggregate the full device inventory across every configured network console.
Read-only operation: it calls list_devices on each network-enabled device and merges the results into one list, tagging every entry with its source device name, plus any per-console errors. Use this to see every AP, switch, gateway, and router across all sites in one view; use list_unifi_devices for the console roster itself, or get_global_health / get_global_client_summary for aggregated health and client counts rather than the raw device records.
Returns: Dict with total_devices, the merged devices list (each tagged _source_device), and an errors list when a console fails.
Inputs: no named parameters.
get_liveviewsARead-only
List all configured UniFi Protect liveviews (camera view layouts).
Read-only operation: it returns each liveview's name, id, and the cameras and layout it includes on the targeted console. Use this to discover view groupings for dashboards or to confirm which cameras belong to a named liveview; it does not return footage or snapshots.
Args: device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: device.
get_motion_eventsARead-only
Return recent camera motion events, resolved to camera names and timestamps.
Read-only operation: it queries Protect motion events over the lookback window, maps each event to its camera name and a human-readable timestamp, and returns the count and per-event list. Requires Protect username/password credentials configured for the console. Use get_smart_detections instead when you need AI classification (person/vehicle/animal/package) rather than raw motion; use get_protect_event_summary for aggregate counts.
Args: hours: Lookback window in hours from now (default 24). limit: Maximum number of events to return (default 50). camera_id: Optional Protect camera identifier or name to filter events to one camera; omit for all cameras. device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: hours, limit, device, camera_id.
get_network_healthARead-only
Return a single overall health summary for one site's network.
Read-only operation: it aggregates WAN/LAN/WLAN status, a composite health score, and device/user tallies into one condensed report. Use get_site_health when you need full per-subsystem detail for that site, get_all_sites_health for a multi-site sweep on one console, or get_global_health for cross-console aggregation.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_networksARead-only
Get all network/VLAN configurations for a site.
Read-only operation: returns each network's name, purpose, VLAN id, subnet CIDR, and DHCP settings. Use create_network / update_network / delete_network to change them, or get_wlans for wireless networks.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
get_observation_retention_statusARead-only
Get aggregate observation count and retained time range.
Read-only operation. Returns how many observations are stored and the earliest-to-latest retained time span. Use to gauge whether query_observation_trends can cover a desired window.
Inputs: no named parameters.
get_optimization_recommendationsARead-only
Analyze a site's configuration and return optimization recommendations.
Read-only operation: it checks channel selection, TX power, VLAN efficiency, port configurations, and bandwidth utilization to suggest improvements. Use analyze_network_issues when you want a fault/issue report instead of proactive tuning advice, or get_device_health_summary for device status only.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_plugin_statusARead-only
List redacted trusted-plugin loading outcomes.
Read-only operation. Returns whether trusted code and sandboxing are active plus each plugin's load outcome. Requires admin scope when called over HTTP. Use to audit which plugins loaded successfully after startup.
Inputs: no named parameters.
get_port_forwardsARead-only
Get all port forwarding rules for a site.
Read-only operation: returns each rule mapping an external port+protocol to an internal IP+port on the gateway. Use this to audit forwards and to find a rule id before delete_port_forward, or create_port_forward to add one.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
get_port_profilesARead-only
Get switch port profile configurations for a site.
Read-only operation: returns each port profile's name and the settings applied to member switch ports (PoE, VLAN, forwarding). Use set_device_port to apply changes to a specific physical port.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
get_protect_accessoriesARead-only
Inventory all UniFi Protect accessories: lights, sensors, chimes, and viewers.
Read-only operation: it queries each accessory type on the targeted console and returns the raw records grouped by type along with a per-type count summary. Use this to audit Protect peripherals alongside cameras; it does not return camera devices (see list_cameras) nor event history.
Args: device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: device.
get_protect_event_summaryARead-only
Summarize all Protect events (motion, smart detections, doorbell) over a window.
Read-only operation: it aggregates event counts by type and camera activity for the lookback window on the targeted console. Requires Protect username/password credentials configured for the console. Use this for a single high-level tally; use get_motion_events or get_smart_detections for the underlying event records, or get_recent_protect_activity for the latest raw events.
Args: hours: Lookback window in hours from now (default 24). device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: hours, device.
get_protect_system_infoARead-only
Return UniFi Protect system information for one console, including device counts.
Read-only operation: it reports the Protect system version, NVR/storage status, and counts of cameras and accessories managed by the targeted console. Use this for a high-level overlay of a Protect deployment; use list_cameras or get_protect_accessories for the individual device inventory, or get_camera_health_summary for camera connectivity.
Args: device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: device.
get_recent_eventsARead-only
Return recent network events (connections, roams, admin actions) for a site.
Read-only operation: it surfaces the newest logged events with type, timestamp, and subject so you can trace what changed on the network. Use get_alarms when you only care about active fault/warning alarms rather than the full event stream; use get_optimization_recommendations or analyze_network_issues for interpreted, actionable findings.
Args: limit: Maximum number of events to return (default 50). site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, limit, device.
get_recent_protect_activityARead-only
Return the most recent Protect events across all cameras as a quick overview.
Read-only operation: it fetches the latest events (up to limit) for the targeted console with camera names and timestamps resolved. Requires Protect username/password credentials configured for the console. Use this for a fast "what just happened" check; use get_protect_event_summary for aggregate counts or get_motion_events/get_smart_detections for filtered, time-windowed history.
Args: limit: Maximum number of recent events to return (default 20). device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: limit, device.
get_routing_tableARead-only
Return the live Layer-3 routing table for a site's gateway.
Read-only operation: it lists each route with destination, next-hop, interface, and source/metric so you can verify static and learned routes. Use get_networks to inspect configured VLAN/subnet definitions rather than active forwarding paths.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_server_healthARead-only
Return redaction-safe UniFi MCP runtime health and service counts.
Read-only operation. Reports counts of registered tools, configured data sources, and plugin status without exposing any secrets. Use to confirm the server and its sources are healthy before issuing deeper queries.
Inputs: no named parameters. Returns: Redaction-safe UniFi MCP server health response.
get_site_healthARead-only
Get comprehensive health status for a site.
Read-only operation: returns per-subsystem health (WAN/LAN/WLAN status, score, and device/user counts) for the named site. Use get_network_health for a lighter summary, or get_global_health across consoles.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
get_site_settingsARead-only
Get the configuration settings for a site.
Read-only operation: returns the site's settings record (network, wireless, and advanced options) as stored on the controller. Use get_sysinfo for controller identity rather than tunable settings.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
get_smart_detectionsARead-only
Return AI smart-detection events (person, vehicle, animal, package) with types.
Read-only operation: it queries Protect smart-detection events over the lookback window, maps each to its camera name and timestamp, and includes the smartDetectTypes and confidence score. Requires Protect username/password credentials configured for the console. Use detection_type to narrow to one class (e.g. "person"); use get_motion_events for raw motion without classification, or get_protect_event_summary for aggregate counts.
Args: hours: Lookback window in hours from now (default 24). limit: Maximum number of events to return (default 50). detection_type: Optional class filter - one of "person", "vehicle", "animal", "package"; omit for all smart-detection types. device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: hours, limit, device, detection_type.
get_snapshot_capabilitiesARead-only
Describe portable snapshot and report capabilities plus native backup limits.
Read-only operation. Returns supported report formats (html, csv), whether native controller backup/restore are available, and the configured source list. Use to learn what export_portable_snapshot and export_network_report can produce before calling them.
Inputs: no named parameters.
get_speed_test_statusARead-only
Return the latest WAN speed-test result and run state for a site.
Read-only operation: it reports download/upload/latency from the most recent test and whether a test is in progress. Use run_speed_test to initiate a new measurement; this does not start one.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_sysinfoARead-only
Get system information for the site controller.
Read-only operation: returns controller identity, firmware version, and hardware/model details for the named site. Use get_site_settings for tunable settings instead of controller metadata.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
get_traffic_analysisARead-only
Analyze site traffic patterns over a configurable time window.
Read-only operation: it reports top talkers, application breakdown (DPI), bandwidth trends, and unusual activity for the lookback period. Use get_traffic_summary for a quick volume-only snapshot, get_dpi_stats for the app breakdown without the time series, or get_client_traffic for one client.
Args: hours: Lookback window in hours from now (default 24). site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, hours, device.
get_traffic_summaryARead-only
Return a condensed traffic-volume summary for a site.
Read-only operation: it reports overall throughput and totals without the per-app or time-series detail. Use get_dpi_stats for application-level breakdown, get_traffic_analysis for windowed trends and top talkers, or get_client_traffic for a specific client.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
get_wlansARead-only
Get all wireless network (SSID) configurations for a site.
Read-only operation: returns each WLAN's name, id, enabled state, guest flag, and security settings. Use create_wlan / update_wlan / delete_wlan to change them, or get_networks for wired networks.
Args: site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: site, device.
kick_clientAIdempotent
Force-disconnect a client; it may reconnect normally.
Mutating operation: drops the active session without a persistent block, so the client can re-associate. Use block_client/unblock_client for a lasting block, or forget_client to remove the client record entirely.
Args: mac: Client MAC address to target. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
list_all_clientsARead-only
List every known client (connected and offline) on a site.
Read-only operation: includes clients not currently connected, so it is the superset of list_clients. Use get_client_details for deep per-client detail or list_clients when you only need active connections.
Args: site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: site, device.
list_camerasARead-only
List every UniFi Protect camera with its online state and identity.
Read-only operation: it returns a summary per camera (name, model, state, and connection status) for the targeted Protect console. Use this to discover the camera_id values needed by get_camera_details, get_camera_snapshot, get_camera_health_summary, and the event tools. Use get_camera_health_summary when you only need aggregate connected/disconnected counts rather than the full per-camera list.
Args: device: Optional Protect console name to target a specific UniFi Protect device; omit to use the first Protect-enabled device.
Inputs: device.
list_client_groupsARead-only
List local client groups and deterministic member counts.
Read-only operation: returns the local groups (local_only) for the controller/site with a deterministic member count per group. Use list_clients_by_organization to enumerate the actual member identities.
Args: site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: site, device.
list_clientsARead-only
List all currently connected (online) clients on a site.
Read-only operation: returns only clients with an active connection at query time. For the historical/known roster including offline clients use list_all_clients; for deep per-client detail use get_client_details.
Args: site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: site, device.
list_clients_by_organizationARead-only
List stable client identities for exactly one local tag or group.
Read-only operation: returns the persisted client keys (MACs) that match a single tag or group filter (local_only). Exactly one of tag or group must be supplied; supplying neither or both is an error. Use list_client_groups to discover group names.
Args: tag: Optional local tag to filter clients by; mutually exclusive with group. group: Optional local group name to filter clients by; mutually exclusive with tag. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: tag, site, group, device.
list_devicesARead-only
List all UniFi network devices (APs, switches, routers) on a site.
Read-only operation: returns a per-device summary for the targeted site, including name, MAC, model, type, IP, online state, uptime, and firmware version. Use this to discover the MAC values needed by get_device_details, restart_device, and the other device tools.
Distinction: use list_unifi_devices to see the server's configured consoles (controller roster); use get_global_inventory for an aggregated inventory across all consoles. This tool lists devices within one site on one console.
Args: site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: site, device.
list_job_runsARead-only
List redacted background job run outcomes.
Read-only operation: returns up to limit recent schedule/job run records
(status, timestamps) with secret values redacted. Use run_schedule_now or
list_schedules to discover runnable schedules.
Args: limit: Maximum number of job runs to return. Defaults to 100.
Inputs: limit.
list_observation_scopesARead-only
List the aggregate observation scopes currently retained.
Read-only operation. Returns the distinct scope dimensions (source, controller, site) present in the observation store. Use to discover valid filter values for query_observation_trends.
Inputs: no named parameters.
list_runtime_eventsARead-only
List normalized events retained by the optional runtime store.
Read-only operation: returns up to limit normalized events persisted by the
runtime store. Requires UNIFI_RUNTIME_ENABLED=true; otherwise unavailable. Use
get_event_polling_status to see which sources feed events.
Args: limit: Maximum number of events to return. Defaults to 100.
Inputs: limit.
list_schedulesARead-only
List allowlisted interval schedules.
Read-only operation: returns the persisted interval schedules (name, job, interval, enabled) and whether background automation is enabled. Use create_interval_schedule to add one, or run_schedule_now to trigger it.
Inputs: no named parameters.
list_sitesARead-only
List all UniFi sites accessible to the current user.
Read-only operation: returns each site's id and name from the targeted console(s). Use get_site_health / get_site_settings for per-site detail once you have a site name.
Args: device: Optional console name to target a specific UniFi device; omit for the default device.
Inputs: device.
list_unifi_devicesARead-only
List every UniFi device (console) configured for this server.
Read-only operation: it returns each configured device's name, controller
URL, site, and the services it exposes (network, protect), plus convenience
lists of network-only and protect-only device names. This is the authoritative
source for the device name accepted by every other tool's optional device
parameter. Use get_global_inventory / get_global_health when you instead want
aggregated data across those consoles rather than the console roster itself.
Returns: Dict with total_devices, a per-device list, and network_devices / protect_devices name lists.
Inputs: no named parameters.
list_webhook_deliveriesARead-only
List redacted webhook delivery and dead-letter state.
Read-only operation: returns up to limit delivery records (status, attempts,
dead-letter state) with secret values redacted. Use test_webhook_destination to
trigger a send, or list_webhook_destinations to see configured endpoints.
Args: limit: Maximum number of delivery records to return. Defaults to 100.
Inputs: limit.
list_webhook_destinationsARead-only
List webhook destinations without secret values.
Read-only operation: returns configured outbound webhook destinations with secret material omitted. Use create_webhook_destination to add one, or list_webhook_deliveries to see send history.
Inputs: no named parameters.
locate_deviceAIdempotent
Enable or disable LED blinking to physically locate a device.
Mutating operation: toggles the locator LED on the device and is persisted on the console. Set enabled=True to start blinking, False to stop. This changes only the LED state and has no effect on connectivity or config.
Args: mac: Device MAC address (case-insensitive; aa:bb:cc:dd:ee:ff or aabbccddeeff). enabled: True to start LED blinking, False to stop. Defaults to True. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device, enabled.
plan_client_qos_policyA
Persist a deterministic QoS target preview without controller mutation.
Mutating (local) operation: resolves selector_type/selector_value to concrete client keys and stores a durable QoS plan (plan_token) on the server with the requested download/upload limits. It does NOT change the controller. Pair the returned plan_token with apply_client_qos_policy to attempt activation. Requires UNIFI_RUNTIME_ENABLED=true; use get_client_qos_capabilities to check adapters.
Args: selector_type: Scope of the policy - "client", "tag", or "group". selector_value: Client identity (MAC/IP/hostname) when selector_type is "client", otherwise the tag or group name to expand to clients. download_kbps: Maximum download bandwidth in kilobits per second. upload_kbps: Maximum upload bandwidth in kilobits per second. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: upload_kbps (required), download_kbps (required), selector_type (required), selector_value (required), +2 more.
poll_events_nowAIdempotent
Poll supported event sources now and durably deduplicate results.
Mutating (local) operation: triggers an immediate poll of matching event sources, inserts new normalized events into the runtime store, and deduplicates against what is already persisted. Requires UNIFI_RUNTIME_ENABLED=true. Use get_event_polling_status to discover source names; use list_runtime_events to read stored results.
Args: source: Optional source name to poll a single source; omit for all sources. device_name: Optional console/device name to filter sources; omit for all.
Inputs: source, device_name.
provision_deviceADestructive
Force re-provision a device with its current configuration.
Mutating operation: re-pushes the existing config to the device and is persisted on the console, without changing firmware or power-cycling like upgrade_device or restart_device. Use after config edits to force the device to re-adopt current settings.
Args: mac: Device MAC address (case-insensitive; aa:bb:cc:dd:ee:ff or aabbccddeeff). site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
query_observation_trendsARead-only
Query bounded UTC trend buckets for an observation kind and metric.
Read-only operation. Returns evenly spaced time buckets between start and end with explicit gaps for missing intervals, so callers can distinguish absence from zero. Bucket size defaults to 300 seconds. Use capture_observations_now first if recent data is missing.
Args: kind: Observation category to query (e.g. "health", "client", "device"). metric: Metric name within the kind (e.g. "latency_ms", "cpu_pct"). start: Inclusive UTC start timestamp (ISO-8601). end: Inclusive UTC end timestamp (ISO-8601). bucket_seconds: Width of each trend bucket in seconds. Defaults to 300. source: Optional source filter (e.g. controller type); omit for all sources. controller: Optional controller identifier filter; omit for all controllers. site: Optional site name filter (e.g. "default"); omit for all sites.
Inputs: end (required), kind (required), start (required), metric (required), +4 more.
reserve_client_ipAIdempotent
Create a DHCP reservation pinning an IP to a client.
Mutating operation: reserves the client's current IP (when ip is omitted) or the given IPv4 address, so the client keeps it across leases. Requires the client to be known; use list_clients to find the current IP if needed.
Args: client: Client MAC address or name to reserve an IP for. ip: Optional IPv4 address to reserve; omit to keep the client's current IP. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: client (required), ip, site, device.
restart_deviceADestructive
Restart (reboot) a UniFi device by MAC address.
Mutating operation: sends a reboot command that is persisted on the console; the device goes offline briefly and reconnects. Unlike provision_device (re-push config without reboot) and upgrade_device (firmware update), this power-cycles the device. No other config change is needed.
Args: mac: Device MAC address (case-insensitive; aa:bb:cc:dd:ee:ff or aabbccddeeff). site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
run_schedule_nowADestructive
Run one allowlisted schedule immediately. Requires confirm=true.
Mutating operation: executes the identified schedule's job once, outside its normal interval, and records the run. Returns success=false unless confirm=true. Use list_job_runs to inspect the outcome; use set_schedule_enabled to disable auto-runs.
Args: schedule_id: Identifier of the schedule to run immediately. confirm: Must be True to run the schedule; without it the call is a no-op. Defaults to False.
Inputs: schedule_id (required), confirm.
run_speed_testAIdempotent
Start an on-demand WAN speed test from the site gateway.
Mutating/long-running operation: it triggers a test against the speed-test endpoint and returns a handle or immediate result; poll get_speed_test_status for completion. Use get_speed_test_status to read the latest result without starting a new test.
Args: site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: site, device.
set_client_tagsAIdempotent
Replace local client tags by stable identity. Requires confirm=true.
Mutating operation: overwrites the client's persisted local tags with the supplied list and is stored on the server (local_only), not the controller. Returns success=false unless confirm=true. Use get_client_organization to read current tags first; use assign_client_group for group membership.
Args: identity: Client MAC, IP, hostname, or alias to resolve to a known client. tags: Full replacement tag list; an empty list clears all tags. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default. confirm: Must be True to apply the change; without it the call is a no-op. Defaults to False.
Inputs: tags (required), identity (required), site, device, +1 more.
set_device_portADestructive
Configure a single switch port: native VLAN, PoE mode, name, or enable state.
Mutating operation: applied immediately and persisted on the console, changing untagged VLAN traffic, PoE delivery, or link state on that port. Only the fields you provide change. Requires confirm=true because a port change can disrupt connectivity for the attached device or downstream network. Use get_device_ports first to find the port_idx and current values.
Args: mac: Device MAC address (case-insensitive; aa:bb:cc:dd:ee:ff or aabbccddeeff). port_idx: Port number to configure (1-based; e.g. 1-24 or SFP 25/26). name: Optional custom port name (e.g. "Cameras"). native_network: Optional network or VLAN name (or its ID) to set as the port's native/untagged VLAN. poe_mode: Optional PoE mode - "auto", "on", "off", or "passv24". forward: Optional VLAN forwarding - "all" (every VLAN) or "customize". enabled: Optional port enable state; True connects, False disables. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default. confirm: Must be True to apply the port change. Defaults to False.
Inputs: mac (required), port_idx (required), name, site, +6 more.
set_firewall_policy_enabledAIdempotent
Enable or disable a zone-based firewall policy.
Mutating operation: applied immediately and persisted on the UniFi console. Targets the policy by id from get_firewall_policies. Predefined controller policies can be toggled but not deleted. Inspect state with get_firewall_policies.
Args: policy_id: Policy id to toggle (from get_firewall_policies). enabled: True to enable, False to disable. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: enabled (required), policy_id (required), site, device.
set_schedule_enabledAIdempotent
Enable or pause a schedule. Requires confirm=true.
Mutating operation: flips the enabled flag on the identified schedule and persists it. Returns success=false unless confirm=true. Use create_interval_schedule to add, or delete_schedule to remove.
Args: schedule_id: Identifier of the schedule to modify. enabled: True to enable (run on interval) or False to pause it. confirm: Must be True to change the schedule; without it the call is a no-op. Defaults to False.
Inputs: enabled (required), schedule_id (required), confirm.
set_webhook_destination_enabledAIdempotent
Enable or pause a webhook destination. Requires confirm=true.
Mutating operation: flips the enabled flag on the identified webhook destination and persists it. Returns success=false unless confirm=true. Use create_webhook_destination to add, or delete_webhook_destination to remove.
Args: destination_id: Identifier of the webhook destination to modify. enabled: True to enable delivery or False to pause it. confirm: Must be True to change the destination; without it the call is a no-op. Defaults to False.
Inputs: enabled (required), destination_id (required), confirm.
test_webhook_destinationADestructive
Send a synthetic payload to a webhook destination. Requires confirm=true.
Mutating (external) operation: dispatches a synthetic test payload to the identified destination and records the delivery outcome. Returns success=false unless confirm=true. Use list_webhook_deliveries to inspect the result.
Args: destination_id: Identifier of the webhook destination to test. confirm: Must be True to send the test payload; without it the call is a no-op. Defaults to False.
Inputs: destination_id (required), confirm.
troubleshoot_clientARead-only
Run a deep-dive troubleshooting analysis for one specific client.
Read-only operation: it examines connection history, signal quality, AP associations, roaming events, and potential issues for the named client. Use get_client_experience_report for a site-wide client-quality overview, or get_client_details for the raw record of one client without the analysis.
Args: mac: MAC address of the client to troubleshoot. site: Site to query. Defaults to "default". device: Optional console/device name to target a specific UniFi console; omit to use the default.
Inputs: mac (required), site, device.
unblock_clientAIdempotent
Remove a prior block so a client can reconnect to the network.
Mutating operation: clears the persistent block set by block_client. Use block_client to re-block, or kick_client for a non-persistent disconnect.
Args: mac: Client MAC address to target. site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
update_cameraADestructive
Update a camera's configuration.
Mutating operation: changes are applied immediately and persisted on the Protect console. Requires username/password configured for the device.
Args: camera: Camera ID or name (resolved by name if not an ID) name: New camera name is_recording_enabled: Enable/disable recording recording_mode: Recording mode — "always", "motion", "smart_detect", "never" device: Optional Protect console name to target a specific UniFi Protect device; omit for first configured Protect device.
Returns: Updated camera configuration
Inputs: camera (required), name, device, recording_mode, +1 more.
update_firewall_ruleADestructive
Update a legacy firewall rule. Only provided fields are changed.
Mutating operation: applied immediately and persisted on the controller. Use get_firewall_rules to find the rule ID first.
Args: rule_id: Firewall rule ID (from get_firewall_rules) name: New rule name action: Action — "accept", "drop", or "reject" protocol: Protocol — "tcp", "udp", "icmp", "all", or IANA number dst_port: Destination port or range src_zone: Source zone ID dst_zone: Destination zone ID src_port: Source port or range logging: Enable/disable logging enabled: Enable/disable the rule site: Site to operate on. Defaults to "default". device: Optional console name to target a specific console; omit for default.
Returns: Updated firewall rule configuration
Inputs: rule_id (required), name, site, action, +8 more.
update_networkADestructive
Update a network/VLAN; only the fields you provide change.
Mutating operation: applied immediately and persisted on the UniFi console. A single field change preserves the network's other settings. Pass both empty dhcp_start and dhcp_stop to disable DHCP. Requires confirm=true because VLAN, routing, or enable-state changes can disconnect clients. Inspect with get_networks.
Args: name: Network name or record id to update. name_new: Rename the network to this value. subnet: New subnet in CIDR form (e.g. "192.168.50.1/24"). vlan: New VLAN id (1-4094); pass -1 to clear VLAN tagging. domain_name: New DNS domain name for clients. dhcp_start: New DHCP pool start IP; pair with dhcp_stop to enable DHCP. dhcp_stop: New DHCP pool end IP; pair with dhcp_start to enable DHCP. dhcp_lease_time: New DHCP lease duration in seconds. enabled: Enable or disable the network. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default. confirm: Safety gate: must be True to apply. Defaults to False.
Inputs: name (required), site, vlan, device, +8 more.
update_site_settingsADestructive
Update site settings.
Mutating operation: changes are applied immediately and persisted. Settings are key-value pairs matching the UniFi site setting schema. Use get_site_settings first to see available settings and their current values.
Args: settings: Dictionary of settings to update (e.g., {"auto_backup_enabled": true}) site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: settings (required), site, device.
update_wlanADestructive
Update a wireless network (SSID); only the fields you provide change.
Mutating operation: applied immediately and persisted on the UniFi console. Any single field updates the matching SSID (resolved by ID or name). Requoting passphrase sets the WiFi password; pmf_mode is disabled|optional|required. Inspect with get_wlans.
Args: wlan: WLAN id or SSID name to update. enabled: Enable or disable the SSID. hide_ssid: Hide the SSID from beacon broadcasts. passphrase: New WiFi password (minimum 8 characters). wpa3_support: Enable WPA3 support on the SSID. wpa3_transition: WPA2/WPA3 transition mode (keeps WPA2 for legacy clients). pmf_mode: Protected Management Frames mode — "disabled", "optional", or "required". bss_transition: Enable 802.11k/v band and AP steering. fast_roaming_enabled: Enable 802.11r fast roaming. site: Site to operate on. Defaults to "default". device: Optional console name to target a specific UniFi device; omit for default.
Inputs: wlan (required), site, device, enabled, +7 more.
upgrade_deviceADestructive
Upgrade a device's firmware to the latest available version.
Mutating operation: initiates a firmware upgrade that is persisted once applied; the device reboots during the update. Unlike restart_device (plain reboot) and provision_device (config re-push), this changes the running firmware. Only proceeds when an upgrade is available on the console.
Args: mac: Device MAC address (case-insensitive; aa:bb:cc:dd:ee:ff or aabbccddeeff). site: Site to operate on. Defaults to "default". device: Optional device name to target a specific console; omit for default.
Inputs: mac (required), site, device.
verify_snapshotARead-only
Verify the schema and checksum of a confined snapshot export.
Read-only operation. Reads the named snapshot from the export directory and validates its schema, redaction status, and content SHA-256. Returns validity plus schema version and checksum for integrity checks. Use after export_portable_snapshot to confirm the file is intact and secret-free.
Args: filename: Name of the snapshot file (within the confined export directory) to validate.
Inputs: filename (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 111 tools
The descriptions are unusually thorough and cross-reference near-neighbors well, but 111 tools creates many clusters where an agent could easily pick the wrong one. Health summaries, traffic views, Protect event tools, and analysis reports all overlap enough that careful reading is required to avoid misselection.
Names overwhelmingly follow a clear verb_noun pattern such as list_*, get_*, create_*, update_*, delete_*, and set_*. Minor inconsistencies exist: reads mix list_ and get_ arbitrarily, global aggregation uses get_global_* alongside get_all_sites_health, and trigger operations use capture_, poll_, run_, and test_ inconsistently.
With 111 tools, this is a severe count mismatch even for a server covering UniFi Network, Protect, and runtime administration. The tool count far exceeds the 25+ threshold for 'too many' and will overwhelm agent context and increase selection errors.
The surface is remarkably broad, covering CRUD for networks, WLANs, firewall rules/policies, client management, schedules, webhooks, and Protect cameras, plus global aggregation and analysis. Notable gaps include no update for firewall policies or port-forwarding rules and no device adoption/forget lifecycle, but most gaps can be worked around.
Maintenance
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Connect AI assistants to explicitly paired computers, servers, and VMs for permitted remote actions.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to manage and monitor UniFi Network Controllers through natural language. Provides 25 read-only tools for discovering devices and clients, viewing security configurations, analyzing network statistics, and exporting configuration data.41MIT
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with access to UniFi Network and Protect infrastructure for managing devices, monitoring clients, analyzing network health, viewing camera snapshots, and getting optimization recommendations across multiple UniFi controllers.2-
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to manage and monitor UniFi network infrastructure through natural language, providing 46 management tools across device, client, WiFi, network, firewall, port forwarding, monitoring, and site management.1MIT
- AlicenseAqualityBmaintenanceEnables querying UniFi network devices and data using natural language through MCP clients like Claude Desktop.4494 npm1MIT