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)

# Clone the repository
git clone https://github.com/gbassaragh/Unifi-mcp.git
cd Unifi-mcp

# Install dependencies
uv sync

Using pip

pip install -e .

Configuration

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

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=false

Device configuration fields:

Field	Description	Default
name	Friendly name for targeting the device	(required)
url	Base URL of the UniFi device	(required)
api_key	API key from UniFi OS Control Plane	(required)
services	Array: ["network"], ["protect"], or both	["network"]
site	Site name for network operations	"default"
verify_ssl	Verify SSL certificates	false
username	Username for Protect events (optional)	null
password	Password for Protect events (optional)	null

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:

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=false

Local Session Auth (Traditional)

For traditional username/password authentication:

UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=false

Cloud API (api.ui.com)

For Ubiquiti Cloud API access:

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

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

{
  "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

# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/Unifi-mcp python -m unifi_mcp.server

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

uv run pytest

Code Formatting

uv run ruff check .
uv run ruff format .

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.