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:
- 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=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 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-provision
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 statistics
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 firewall rulesget_routing_table- Get routing table
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 analysistroubleshoot_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 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.