{
  "markdown": "# UniFi MCP Server\n\nmcp-name: io.github.mikeholownych/unifi-mcp\n\n[![CI](https://github.com/mikeholownych/unifi-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mikeholownych/unifi-mcp/actions/workflows/ci.yml)\n[![unifi-mcp MCP server](https://glama.ai/mcp/servers/mikeholownych/unifi-mcp/badges/score.svg)](https://glama.ai/mcp/servers/mikeholownych/unifi-mcp)\n[![Smithery](https://img.shields.io/badge/Smithery-mike--holownych%2Funifi--mcp-purple)](https://smithery.ai/server/mike-holownych/unifi-mcp)\n\nAn 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.\n\n> **Credits:** This project started as a fork of [gbassaragh/Unifi-mcp](https://github.com/gbassaragh/Unifi-mcp) and has since evolved into a fully independent project. Thanks to [@gbassaragh](https://github.com/gbassaragh) for the excellent starting point.\n\n## Improvements Over Upstream\n\n- **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.\n- **Mode-aware base URL resolution** — `api_base_url` now respects the configured auth mode instead of unconditionally returning the Integration API endpoint.\n- **Expanded test suite** — 250+ passing tests covering configuration, MCP compatibility, runtime persistence, network client behavior, server tool registration, and Protect integrations.\n\n## Features\n\n### UniFi Network\n- **Device Management**: List, restart, locate, and upgrade UniFi devices (APs, switches, routers)\n- **Client Management**: Monitor connected clients, block/unblock, view traffic statistics\n- **Site Management**: View site health, network configurations, VLANs, and wireless settings\n- **Statistics & Monitoring**: Events, alarms, speed tests, and DPI statistics\n- **AI-Powered Insights**: Network analysis, optimization recommendations, and troubleshooting\n\n### UniFi Protect\n- **Camera Management**: List cameras, view status, get live snapshots\n- **System Monitoring**: NVR status, camera health summaries\n- **Accessories**: Manage lights, sensors, chimes, and viewers\n- **Liveviews**: Access configured camera view layouts\n\n### Multi-Device Support\n- Configure multiple UniFi devices (gateways, NVRs, etc.)\n- Target specific devices by name — **all** network and Protect tools accept an optional `device` parameter\n- Per-device API keys: each configured device authenticates with its own key\n- Mix of Network and Protect services across devices\n\n### Events and Safe Automation\n- Normalize and durably deduplicate Network and Protect events in optional SQLite storage\n- Poll each configured source independently and report unsupported capabilities explicitly\n- Run only built-in interval jobs: `poll_events`, `retry_webhook_deliveries`, `capture_observations`, and `prune_runtime_data`\n- Deliver filtered, signed HTTPS webhooks with bounded retries and dead-letter state\n- Keep persistence, background automation, and private webhook destinations disabled by default\n\n### Authentication Modes\n\n| Mode | Auth | Best for |\n|------|------|----------|\n| `local_api_key` | Integration API key | Recommended default; broad read access |\n| `local` | Username/password session | Full feature access: firewall rules, WLAN configs, site settings, events, alarms, DPI |\n| `cloud` | api.ui.com key | Remote/cloud-managed controllers |\n\nWhen 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.\n\n> **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`.\n\n## Agent Skills\n\nBundled skills (in [`skills/`](skills/)) teach agents proven workflows for this server — including\ncontroller-specific gotchas (Network 10 removed endpoints, zone-pair rules, WPA3 transition).\n\n**Full documentation**: See [`SKILLS.md`](SKILLS.md) for usage guide, expected results, troubleshooting, and how to request new functionality.\n\n### Quick reference\n\n| Skill | Type | Purpose |\n|---|---|---|\n| `unifi-network-audit` | read-only | Full site audit: devices, clients, WiFi posture, firewall, structured report |\n| `unifi-troubleshoot-client` | read-only | Diagnose a misbehaving device: RF, roaming, blocking, IP layer |\n| `unifi-wifi-optimize` | write-gated | Channel plan, widths, WPA3 transition, band steering — approval-gated |\n| `unifi-grant-device-access` | write-gated | Give a device a reserved IP + scoped zone-firewall access |\n| `unifi-internet-down` | read-only triage | \"Internet is dead!\" — plain-English outage diagnosis, ISP escalation script |\n| `unifi-whos-home` | read-only | \"Who's on my WiFi?\" — friendly inventory, intruder checks with randomized-MAC awareness |\n| `unifi-setup-new-device` | write-gated | Get any new gadget online: pairing pitfalls (2.4GHz/WPA3), naming, IP reservation |\n| `unifi-dns-triage` | read-only | \"Site won't load but ping works\" — resolution vs connectivity split, forced-internal-DNS patterns |\n| `unifi-mdns-discovery` | read-only+ | AirPrint/Cast broken across VLANs — mDNS reflection, IGMP/IPTV cautions |\n| `unifi-port-forwarding` | write-gated | Self-hosted service exposure incl. hairpin NAT, CGNAT detection, zone-policy pairing |\n| `unifi-vpn` | write-gated | WireGuard/Teleport setup + failure ladder (handshake/MTU/zone-policies) |\n| `unifi-firmware-campaign` | write-gated | Staged firmware updates: snapshot, canary, verify, stuck-device ladder |\n| `unifi-mesh-backhaul` | read-only | Slow far-room WiFi: wireless-uplink/hop diagnosis, wired-backhaul guidance |\n| `unifi-ids-ips-triage` | read-only+ | Threat alerts: false-positive vs real, suppression, IPS throughput cost |\n| `unifi-backup-migration` | write-gated | What backups contain, migration rules of thumb, pre-migration snapshots |\n| `unifi-network-map` | doc-writer | Persistent labeled topology (zones/VLANs/deps) that sharpens every other skill |\n\n### How skills work\n\nJust describe your problem naturally — the agent matches your request to the right skill and follows its workflow:\n\n- **\"My internet is down\"** → `unifi-internet-down` diagnoses WAN, modem, gateway\n- **\"Who's on my WiFi?\"** → `unifi-whos-home` lists devices, flags unknowns\n- **\"Audit my network\"** → `unifi-network-audit` produces a full health report\n- **\"Set up my new TV\"** → `unifi-setup-new-device` guides WiFi pairing\n\n**Write-gated skills** (marked above) modify your network — they always ask approval before applying changes.\n\nSkills for non-technical users avoid jargon, translate every technical term,\nand require confirmation before disruptive actions.\n\n**Install** (per project): copy into `.claude/skills/`:\n\n```bash\ngit clone https://github.com/mikeholownych/unifi-mcp.git\nmkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/\n```\n\nSee [`SKILLS.md`](SKILLS.md) for full usage guide, expected results, troubleshooting, and how to request new functionality.\n\nSkills reference MCP tools by their plain names (`get_firewall_policies`, …);\nyour MCP client prefixes them automatically.\n\n## Supported Hardware\n\n- UniFi Dream Machine (UDM, UDM-Pro, UDM-SE)\n- UniFi Cloud Gateway (UCG-Ultra, UCG-Fiber)\n- UniFi Network Video Recorder (UNVR, UNVR-Pro)\n- UniFi Network Application (self-hosted)\n- Traditional Cloud Key (Gen1, Gen2, Gen2+)\n\n## Limitations & Supported Versions\n\nThis server is built for operation **on a trusted local network**, talking to UniFi\nconsoles by IP address. With that in mind:\n\n- **TLS verification is disabled by default** (`UNIFI_VERIFY_SSL=false`). UniFi OS\n  ships self-signed certificates, and controllers are reached by IP on the LAN, so\n  certificate verification is expected to fail. Enable `UNIFI_VERIFY_SSL=true` only\n  when your controller presents a CA-trusted certificate.\n- **No device configured at startup is allowed.** The server boots and exposes all\n  tools even before `UNIFI_*` credentials are supplied (e.g. when deployed and\n  configured via environment variables). Device-bound tool calls then return a clear\n  `No device configured` error until a device is set.\n- **Scope enforcement applies to remote transports only.** When running over\n  Streamable HTTP, every `tools/call` is gated by read/write/admin OIDC scopes, and\n  startup fails if any tool is unclassified. Over stdio (local IPC) no auth is\n  required — stdio is assumed to be a trusted local process.\n- **Integration API key limitations.** A subset of controller features is only\n  available via legacy session auth (`UNIFI_MODE=local`): network events, alarms,\n  DPI statistics, speed tests, WLAN/firewall configs, port profiles, and routing\n  tables. Tools for these return a clear error explaining how to enable them.\n- **Tested against recent UniFi OS / Network / Protect.** Newer controllers that\n  removed legacy endpoints (e.g. UniFi Network 10 removed alarms/events endpoints)\n  are handled by degrading gracefully rather than erroring.\n- **Not a substitute for controller backups.** Snapshots and reports are read-only\n  exports; they do not configure or restore a controller.\n\n## Installation\n\n### Using uv (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/mikeholownych/unifi-mcp.git\ncd unifi-mcp\n\n# Install dependencies\nuv sync\n```\n\n### Using pip\n\n```bash\npip install -e .\n```\n\n## Configuration\n\nCreate a `.env` file in the project root (or set environment variables). See [.env.example](.env.example) for all options.\n\n`UNIFI_CACHE_TTL` controls the shared GET cache lifetime across client instances (default: 30\nseconds). Mutation verification defaults to five fresh reads with exponential delays of 0.5, 1,\n2, and 2 seconds. Tune this with `UNIFI_MUTATION_VERIFY_ATTEMPTS`,\n`UNIFI_MUTATION_VERIFY_INITIAL_DELAY`, and `UNIFI_MUTATION_VERIFY_MAX_DELAY` when a controller\nconverges more slowly or quickly.\n\n### Optional Runtime Persistence\n\nSQLite-backed runtime persistence is disabled by default. Enable it only when persistent runtime state is needed:\n\n```bash\nUNIFI_RUNTIME_ENABLED=true\n```\n\nBy 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`.\n\nSet an explicit data directory or database path when needed:\n\n```bash\nUNIFI_DATA_DIR=/var/lib/unifi-mcp\nUNIFI_RUNTIME_DATABASE=/var/lib/unifi-mcp/runtime.db\n```\n\n`UNIFI_DATA_DIR` and `UNIFI_RUNTIME_DATABASE` must resolve to absolute paths. `UNIFI_RUNTIME_DATABASE` overrides the database derived from `UNIFI_DATA_DIR`.\n\n### Events, Schedules, and Webhooks\n\nRuntime persistence enables event storage and management tools, but does not start background work. Enable the scheduler separately:\n\n```bash\nUNIFI_RUNTIME_ENABLED=true\nUNIFI_AUTOMATION_ENABLED=true\n```\n\nEvent ingestion is capability-based polling, not a claim of universal UniFi push support:\n\n- Network event polling requires traditional local session auth with `UNIFI_MODE=local`.\n- Protect event polling requires a configured local `username` and `password` for each Protect device.\n- Integration API and cloud Network configurations are reported as unsupported for event polling.\n- Polling uses overlap plus durable source-key deduplication so timestamp boundaries do not create duplicate records.\n\nSchedules 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.\n\nWebhook 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.\n\nSigning secrets never enter SQLite or MCP arguments. Set a secret in the server environment, then pass only its variable name as `secret_env_name`:\n\n```bash\nWEBHOOK_SECRET_AUTOMATION='replace-with-a-random-secret'\n```\n\nUseful 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.\n\n### Portable Snapshots and Reports\n\nPortable 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.\n\n```bash\n# Optional absolute override; defaults to <UNIFI_DATA_DIR>/exports\nUNIFI_EXPORT_DIR=/var/lib/unifi-mcp/exports\n```\n\nExport 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.\n\nNative 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.\n\n### History and Prometheus\n\nWith 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.\n\nPrometheus support is not part of the base dependency set and starts no listener by default:\n\n```bash\nuv sync --extra observability\nUNIFI_RUNTIME_ENABLED=true\nUNIFI_PROMETHEUS_ENABLED=true\nUNIFI_PROMETHEUS_HOST=127.0.0.1\n```\n\nMetrics 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.\n\n### Client Organization and QoS Previews\n\nWith 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.\n\nOrganization 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.\n\n`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.\n\n### Trusted Plugins\n\nPlugins 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`.\n\nPlugins use API version 1 and the `unifi_mcp.plugins` entry-point group:\n\n```toml\n[project.entry-points.\"unifi_mcp.plugins\"]\nexample = \"example_package.plugin:plugin\"\n```\n\nThe 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.\n\n### Streamable HTTP and OIDC\n\nStdio 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:\n\n```bash\nUNIFI_TRANSPORT=streamable-http\nUNIFI_HTTP_HOST=127.0.0.1\nUNIFI_HTTP_PORT=8000\nUNIFI_HTTP_PATH=/mcp\nUNIFI_HTTP_PUBLIC_URL=https://mcp.example.com/mcp\nUNIFI_OIDC_ISSUER=https://identity.example.com\nUNIFI_OIDC_AUDIENCE=unifi-mcp\nUNIFI_OIDC_ALGORITHMS=RS256\n```\n\nDiscovery 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.\n\nAll 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.\n\n### Multi-Device Configuration (Recommended)\n\nConfigure multiple UniFi devices with different services:\n\n```bash\nUNIFI_DEVICES='[\n  {\n    \"name\": \"main-gateway\",\n    \"url\": \"https://192.168.1.1\",\n    \"api_key\": \"your-gateway-api-key\",\n    \"services\": [\"network\"],\n    \"site\": \"default\"\n  },\n  {\n    \"name\": \"nvr\",\n    \"url\": \"https://192.168.1.2\",\n    \"api_key\": \"your-nvr-api-key\",\n    \"services\": [\"network\", \"protect\"],\n    \"site\": \"default\"\n  }\n]'\nUNIFI_VERIFY_SSL=false\n```\n\n**Device configuration fields:**\n| Field | Description | Default |\n|-------|-------------|---------|\n| `name` | Friendly name for targeting the device | (required) |\n| `url` | Base URL of the UniFi device | (required) |\n| `api_key` | API key from UniFi OS Control Plane | (required) |\n| `services` | Array: `[\"network\"]`, `[\"protect\"]`, or both | `[\"network\"]` |\n| `site` | Site name for network operations | `\"default\"` |\n| `verify_ssl` | Verify SSL certificates | `false` |\n| `username` | Username for Protect events (optional) | `null` |\n| `password` | Password for Protect events (optional) | `null` |\n\n**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.\n\nTo create an API key:\n1. Log into your UniFi controller\n2. Go to Settings → Control Plane → API\n3. Create a new API key with appropriate permissions\n\n### Legacy Single-Device Configuration\n\nFor backwards compatibility, single-device configuration is still supported:\n\n```bash\nUNIFI_MODE=local_api_key\nUNIFI_CONTROLLER_URL=https://192.168.1.1\nUNIFI_CLOUD_API_KEY=your-api-key\nUNIFI_SITE=default\nUNIFI_VERIFY_SSL=false\n```\n\n### Local Session Auth (Traditional)\n\nFor full-feature access with username/password authentication:\n\n```bash\nUNIFI_MODE=local\nUNIFI_CONTROLLER_URL=https://192.168.1.1\nUNIFI_USERNAME=local-admin\nUNIFI_PASSWORD=your-password\nUNIFI_SITE=default\nUNIFI_IS_UDM=true\nUNIFI_VERIFY_SSL=false\n```\n\n### Cloud API (api.ui.com)\n\nFor Ubiquiti Cloud API access:\n\n```bash\nUNIFI_MODE=cloud\nUNIFI_CLOUD_API_KEY=your-api-key\n```\n\nGet your API key from [unifi.ui.com](https://unifi.ui.com) → API section.\n\n## Usage with Claude Desktop\n\nAdd to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/unifi-mcp\", \"python\", \"-m\", \"unifi_mcp.server\"],\n      \"env\": {\n        \"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\\\"]}]\",\n        \"UNIFI_VERIFY_SSL\": \"false\"\n      }\n    }\n  }\n}\n```\n\n## Usage with Claude Code / opencode\n\n```bash\n# Add the MCP server\nclaude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.server\n```\n\nOr in `opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"unifi\": {\n      \"type\": \"local\",\n      \"command\": [\"/path/to/unifi-mcp/.venv/bin/python\", \"-m\", \"unifi_mcp.server\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Server Health\n- `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.\n\n### Multi-Device Management\n- `list_unifi_devices` - List all configured UniFi devices and their services\n\n### Device Management\n- `list_devices` - List all UniFi network devices\n- `get_device_details` - Get detailed device information\n- `restart_device` - Restart a device\n- `locate_device` - Blink LED to locate device\n- `get_device_stats` - Get performance statistics\n- `upgrade_device` - Upgrade firmware\n- `provision_device` - Force re-provision\n- `get_device_ports` - List switch/gateway port configuration and link state\n- `set_device_port` - Configure one port; requires `confirm=true` and verifies controller read-back\n\n### Client Management\n- `list_clients` - List connected clients\n- `list_all_clients` - List all known clients (including offline)\n- `get_client_details` - Get client details\n- `block_client` / `unblock_client` - Block/unblock clients\n- `kick_client` - Disconnect a client\n- `forget_client` - Remove from known clients\n- `get_client_traffic` - Get traffic statistics\n- `reserve_client_ip` - Reserve IP via DHCP reservation\n- `get_client_organization` / `set_client_tags` - Read or replace durable local tags\n- `create_client_group` / `delete_client_group` - Manage local-only groups\n- `assign_client_group` / `list_client_groups` - Manage and inspect single-group membership\n- `list_clients_by_organization` - Resolve deterministic tag or group target sets\n- `get_client_qos_capabilities` - Report validated controller QoS support\n- `plan_client_qos_policy` / `apply_client_qos_policy` - Preview QoS targets and apply only when a validated adapter exists\n\n### Site Management\n- `list_sites` - List all sites\n- `get_site_health` - Get site health status\n- `get_site_settings` - Get site settings\n- `get_sysinfo` - Get system information\n- `get_networks` - Get network/VLAN configs\n- `get_wlans` - Get wireless network configs\n- `get_port_profiles` - Get switch port profiles\n- `get_firewall_rules` - Get legacy firewall rules\n- `get_firewall_policies` - Get zone-based firewall policies (UniFi Network 9+)\n- `get_routing_table` - Get routing table\n- `get_port_forwards` - Get port forwarding rules\n- `create_port_forward` / `delete_port_forward` - Manage port forwards\n\n### Configuration Management (writes)\n- `create_network` / `update_network` / `delete_network` - Manage networks and VLANs; each requires `confirm=true` and verifies controller read-back\n- `create_wlan` / `update_wlan` / `delete_wlan` - Manage wireless networks\n- `create_firewall_policy` / `set_firewall_policy_enabled` / `delete_firewall_policy` - Manage zone-based firewall policies\n- `export_camera_clip` - Export an MP4 beneath `UNIFI_EXPORT_DIR`; requires `confirm=true`\n- `get_all_sites_health` - Health overview across all sites\n\nWrite tools that remove data or cause disruption are confirm-gated or flagged destructive via MCP annotations.\n\n### Statistics & Monitoring\n- `get_network_health` - Overall network health\n- `get_recent_events` - Recent events\n- `get_alarms` - Active alarms\n- `archive_all_alarms` - Archive all alarms\n- `run_speed_test` - Start speed test\n- `get_speed_test_status` - Get speed test results\n- `get_dpi_stats` - DPI statistics\n- `get_traffic_summary` - Traffic summary\n\n### AI Insight Tools\n- `analyze_network_issues` - Comprehensive issue analysis\n- `get_optimization_recommendations` - Configuration recommendations\n- `get_client_experience_report` - Client quality metrics\n- `get_device_health_summary` - Device health overview\n- `get_traffic_analysis` - Traffic pattern analysis\n- `get_all_sites_health` - Health overview across all sites\n\n### Multi-Site Orchestration\n- `get_global_inventory` - Unified device inventory across all controllers\n- `get_global_health` - Aggregated health report across all controllers\n- `get_global_client_summary` - Client counts, top talkers, blocked clients across all controllers\n- `troubleshoot_client` - Deep-dive client troubleshooting\n\n### UniFi Protect\n- `list_cameras` - List all cameras with connection status\n- `get_camera_details` - Get detailed camera information\n- `get_camera_snapshot` - Get live snapshot (base64 JPEG)\n- `get_protect_system_info` - Get NVR system information\n- `get_camera_health_summary` - Camera health overview with issues\n- `get_liveviews` - Get configured liveview layouts\n- `get_protect_accessories` - List lights, sensors, chimes, viewers\n\n### UniFi Protect Events (require username/password)\n- `get_motion_events` - Get recent motion events\n- `get_smart_detections` - Get smart detection events (person, vehicle, animal, package)\n- `get_protect_event_summary` - Summary of all events by type\n- `get_recent_protect_activity` - Quick overview of recent activity\n\n## Example Conversations\n\nAfter connecting the MCP server, you can ask Claude:\n\n### Network Management\n- \"List all my UniFi devices\"\n- \"What's the current network health?\"\n- \"Analyze my network for any issues\"\n- \"What optimization recommendations do you have?\"\n- \"Show me client experience metrics\"\n- \"Troubleshoot the client with MAC aa:bb:cc:dd:ee:ff\"\n- \"Which clients are using the most bandwidth?\"\n- \"Are there any devices that need firmware updates?\"\n- \"Show me the recent network events\"\n- \"Run a speed test\"\n\n### UniFi Protect\n- \"List all my cameras\"\n- \"Show me the camera health summary\"\n- \"Get a snapshot from the Front Door camera\"\n- \"What's the status of my NVR?\"\n- \"Are any cameras disconnected?\"\n- \"Show me the protect accessories\"\n\n### Protect Events (requires credentials)\n- \"Show me recent motion events\"\n- \"What smart detections happened in the last 24 hours?\"\n- \"Were there any person detections today?\"\n- \"Give me an event summary for the past week\"\n- \"Show recent activity from the Front Door camera\"\n\n### Multi-Device\n- \"List my configured UniFi devices\"\n- \"Show cameras on my NVR\"\n- \"Get network health from the main gateway\"\n\n## Development\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Code Formatting\n\n```bash\nuv run ruff check .\nuv run ruff format .\n```\n\n### Docker\n\n```bash\ndocker build -t unifi-mcp .\ndocker run -i --rm --env-file .env unifi-mcp\n```\n\nTo enable optional runtime persistence, mount a named volume at the image's writable `/data` directory:\n\n```bash\ndocker run -i --rm \\\n  --env-file .env \\\n  --env UNIFI_RUNTIME_ENABLED=true \\\n  --env UNIFI_DATA_DIR=/data \\\n  --volume unifi-mcp-data:/data \\\n  unifi-mcp\n```\n\n`--rm` removes the stopped container, but the `unifi-mcp-data` named volume remains and preserves `/data/runtime.db` for subsequent runs.\n\n## Requesting new functionality\n\n- **New skills**: Open an issue with `[Skill]` prefix — describe the problem, workflow, and expected output\n- **Modify skills**: Open an issue with `[Skill: skill-name]` prefix — what's missing or broken\n- **New tools**: Open an issue with `[Tool]` prefix — include the UniFi API endpoint and expected format\n\nSee [`SKILLS.md`](SKILLS.md) for detailed contribution guidelines.\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history and [CONTRIBUTING.md](CONTRIBUTING.md) to contribute.\n\n## Security Notes\n\n- Credentials are passed via environment variables — never commit `.env`\n- **TLS verification is disabled by default** (`UNIFI_VERIFY_SSL=false`) because the\n  server is designed to run on a trusted LAN against UniFi consoles reached by IP\n  with self-signed certificates. Enable it only with a CA-trusted certificate.\n- Over stdio (local IPC), no authentication is required — the transport is assumed\n  to be a trusted local process. Over Streamable HTTP, all tool calls require a\n  valid OIDC token with the appropriate read/write/admin scope, enforced server-side.\n- The server exposes both read and write tools\n- Disruptive or destructive tools are annotated and/or explicitly confirm-gated where implemented; MCP clients decide how to present or honor annotations\n- Especially dangerous operations such as factory reset remain unexposed\n- API keys should be kept secure and rotated periodically\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n",
  "bytes": 30381,
  "sha": "e0339fe81668e1a8557e70507d461e290f752b6f1839072e0d6e5f963cd6cafc",
  "repo_slug": "mikeholownych/unifi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mikeholownych_unifi_mcp_56ba7ada/readme"
}