UniFi MCP Server

An MCP (Model Context Protocol) server that provides AI assistants like Claude with access to UniFi Network and Protect infrastructure management and analysis capabilities.

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

• Mix of Network and Protect services across devices

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

Installation

Using uv (Recommended)

Using pip

Configuration

Create a .env file in the project root (or set environment variables).

Multi-Device Configuration (Recommended)

Configure multiple UniFi devices with different services:

Device configuration fields:

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:

1. Log into your UniFi controller

2. Go to Settings → Control Plane → API

3. Create a new API key with appropriate permissions

Legacy Single-Device Configuration

For backwards compatibility, single-device configuration is still supported:

Local Session Auth (Traditional)

For traditional username/password authentication:

Cloud API (api.ui.com)

For Ubiquiti Cloud API access:

Get 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):

Usage with Claude Code

Available Tools

Multi-Device Management

• list_unifi_devices - List all configured UniFi devices and their services

Device Management

• list_devices - List all UniFi network devices

• get_device_details - Get detailed device information

• restart_device - Restart a device

• locate_device - Blink LED to locate device

• get_device_stats - Get performance statistics

• upgrade_device - Upgrade firmware

• provision_device - Force re-provision

Client Management

• list_clients - List connected clients

• list_all_clients - List all known clients (including offline)

• get_client_details - Get client details

• block_client / unblock_client - Block/unblock clients

• kick_client - Disconnect a client

• forget_client - Remove from known clients

• get_client_traffic - Get traffic statistics

Site Management

• list_sites - List all sites

• get_site_health - Get site health status

• get_site_settings - Get site settings

• get_sysinfo - Get system information

• get_networks - Get network/VLAN configs

• get_wlans - Get wireless network configs

• get_port_profiles - Get switch port profiles

• get_firewall_rules - Get firewall rules

• get_routing_table - Get routing table

Statistics & Monitoring

• get_network_health - Overall network health

• get_recent_events - Recent events

• get_alarms - Active alarms

• archive_all_alarms - Archive all alarms

• run_speed_test - Start speed test

• get_speed_test_status - Get speed test results

• get_dpi_stats - DPI statistics

• get_traffic_summary - Traffic summary

AI Insight Tools

• analyze_network_issues - Comprehensive issue analysis

• get_optimization_recommendations - Configuration recommendations

• get_client_experience_report - Client quality metrics

• get_device_health_summary - Device health overview

• get_traffic_analysis - Traffic pattern analysis

• troubleshoot_client - Deep-dive client troubleshooting

UniFi Protect

• list_cameras - List all cameras with connection status

• get_camera_details - Get detailed camera information

• get_camera_snapshot - Get live snapshot (base64 JPEG)

• get_protect_system_info - Get NVR system information

• get_camera_health_summary - Camera health overview with issues

• get_liveviews - Get configured liveview layouts

• get_protect_accessories - List lights, sensors, chimes, viewers

UniFi Protect Events (require username/password)

• get_motion_events - Get recent motion events

• get_smart_detections - Get smart detection events (person, vehicle, animal, package)

• get_protect_event_summary - Summary of all events by type

• get_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

Code Formatting

Security Notes

• Credentials are passed via environment variables

• SSL verification is disabled by default for self-signed certificates

• The server only exposes read operations and safe management commands

• Destructive operations (delete site, factory reset) are not exposed

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