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_url now 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.

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 device parameter
• Per-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, and prune_runtime_data
• Deliver filtered, signed HTTPS webhooks with bounded retries and dead-letter state
• Keep persistence, background automation, and private webhook destinations disabled by default

Authentication Modes

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

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-down diagnoses WAN, modem, gateway
• "Who's on my WiFi?" → unifi-whos-home lists devices, flags unknowns
• "Audit my network" → unifi-network-audit produces a full health report
• "Set up my new TV" → unifi-setup-new-device guides 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. Enable UNIFI_VERIFY_SSL=true only 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 clear No device configured error until a device is set.
• Scope enforcement applies to remote transports only. When running over Streamable HTTP, every tools/call is 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 sync

Using pip

pip install -e .

Configuration