home / mcp / unifi mcp server

UniFi MCP Server

Provides AI-assisted UniFi Network and Protect management capabilities via an MCP server with multi-device configuration.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "gbassaragh-unifi-mcp": {
      "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"
      }
    }
  }
}

You run a unified MCP server that gives AI assistants access to UniFi Network and Protect capabilities for management, monitoring, and insights. This server lets you configure multiple UniFi devices, inquire about health and status, control devices, and pull live data through concise, AI-assisted commands. It’s designed to be easy to install, configure, and use from your preferred MCP client.

How to use

Connect your MCP client to the UniFi MCP Server using the provided stdio configuration. You run the MCP server locally and request actions or data from your UniFi devices through clear, natural prompts. The tools cover device management, site and network health, client activity, camera status, and Protect events, all wrapped in a consistent command surface.

How to install

Prerequisites you need before installation: a Python runtime and the MCP runner. Ensure you have Python installed and that you can run the MCP client tool used to host your server.

# Choose installation method and run commands as shown
# Option 1: using uv (Recommended)
# Clone the MCP package repository
git clone https://github.com/gbassaragh/Unifi-mcp.git
cd Unifi-mcp

# Install dependencies via the MCP runner
uv sync

# Option 2: install via Python in editable mode
pip install -e .

Configuration and usage notes

Configure your UniFi devices by providing connection details and the services you want to expose. The standard approach is to define multiple devices, each with a name, URL, API key, and the services you want to enable (network, protect, or both). The configuration supports multi-device setups and SSL verification control for environments with self-signed certificates.

{
  "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\"
  }]"
}

Security and run-time considerations

Credentials and sensitive data are provided through environment variables at runtime. SSL verification can be disabled for self-signed certificates in development environments. The server exposes read operations and safe management commands; destructive actions (such as deleting a site or factory resetting devices) are not exposed.

Development and testing tips

You can run unit tests to verify behavior and use formatting and linting tools to keep the codebase clean during development. Use the provided commands to run tests and format code.

Available tools

list_unifi_devices

List all configured UniFi devices and their services.

list_devices

List all UniFi network devices.

get_device_details

Get detailed information about a specific device.

restart_device

Restart a device.

locate_device

Blink the device indicator to locate it physically.

get_device_stats

Retrieve performance statistics for a device.

upgrade_device

Upgrade the device firmware.

provision_device

Force re-provision of a device.

list_clients

List connected clients.

list_all_clients

List all known clients, including offline ones.

get_client_details

Get details for a specific client.

block_client

Block a client from accessing the network.

unblock_client

Unblock a previously blocked client.

kick_client

Disconnect a client from the network.

forget_client

Remove a client from known clients.

get_client_traffic

Get traffic statistics for a client.

list_sites

List all sites.

get_site_health

Get the health status of a site.

get_site_settings

Get settings for a site.

get_sysinfo

Get system information.

get_networks

Get network/VLAN configurations.

get_wlans

Get wireless network configurations.

get_port_profiles

Get switch port profiles.

get_firewall_rules

Get firewall rules.

get_routing_table

Get routing table.

get_network_health

Overall network health.

get_recent_events

Recent events in the network.

get_alarms

Active alarms.

archive_all_alarms

Archive all alarms.

run_speed_test

Start a network speed test.

get_speed_test_status

Get speed test results.

get_dpi_stats

DPI statistics.

get_traffic_summary

Traffic summary.

analyze_network_issues

Comprehensive network issue analysis.

get_optimization_recommendations

Configuration optimization recommendations.

get_client_experience_report

Client quality metrics report.

get_device_health_summary

Device health overview.

get_traffic_analysis

Traffic pattern analysis.

troubleshoot_client

Deep-dive client troubleshooting.

list_cameras

List all cameras with status.

get_camera_details

Get detailed camera information.

get_camera_snapshot

Get a live camera snapshot (base64 JPEG).

get_protect_system_info

Get NVR system information.

get_camera_health_summary

Camera health overview including issues.

get_liveviews

Get configured Protect liveview layouts.

get_protect_accessories

List lights, sensors, chimes, and viewers.

get_motion_events

Get recent motion events.

get_smart_detections

Get smart detection events (person, vehicle, animal, package).

get_protect_event_summary

Summary of events by type for Protect.

get_recent_protect_activity

Recent Protect activity overview.