UniFi

You run an MCP (Model Context Protocol) server to let AI assistants interact with your UniFi network for monitoring, management, and configuration tasks. It exposes a simple, scriptable interface you can run locally or via Docker, so you can automate actions like listing devices, checking health, and controlling clients from your preferred tools.

How to use

You use an MCP client to connect to the UniFi MCP Server and perform actions such as listing devices, checking site health, and managing clients. Start the MCP server using either Docker or a local installation, then point your client at the active MCP endpoint. When you issue commands, the server responds with structured results you can parse in your automation flows or chat assistants.

Typical workflows include: setting up a connection to your UniFi Controller, retrieving device inventories, getting health status for a site, listing networks, and performing device actions like restarting a device or blocking a client. You’ll configure the client with the host, authentication details, and SSL verification preferences, then run queries or actions supported by the server’s tool set.

How to install

Prerequisites you need before installation: a working container runtime if you choose Docker, or a Python environment if you install locally. Ensure you have network access to your UniFi Controller and that you know your controller credentials.

Option 1. Docker (Recommended) to run the MCP server:

# Clone the repository
git clone https://github.com/nntkio/unifiMCP.git
cd unifiMCP

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your UniFi controller details

# Build and run with Docker Compose
docker compose up -d

Option 2. Local installation (without Docker):

# Clone the repository
git clone https://github.com/nntkio/unifiMCP.git
cd unifiMCP

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[dev]"

Configuration

Before running the server, configure the required environment variables to tell the MCP server how to reach your UniFi Controller and how to operate.

Key environment variables to set (examples shown):

# Standard Controller (port 8443)
export UNIFI_HOST="https://192.168.1.1:8443"
export UNIFI_USERNAME="admin"
export UNIFI_PASSWORD="your-password"
export UNIFI_SITE="default"
export UNIFI_VERIFY_SSL="false"
export UNIFI_IS_UNIFI_OS="false"

# UniFi OS Device (UDM/UDM Pro - port 443)
export UNIFI_HOST="https://192.168.1.1"
export UNIFI_USERNAME="admin"
export UNIFI_PASSWORD="your-password"
export UNIFI_SITE="default"
export UNIFI_VERIFY_SSL="false"
export UNIFI_IS_UNIFI_OS="true"

Claude Desktop configuration

You can connect Claude Desktop to the MCP server by adding a server entry in the Claude configuration. Use either a local installation or Docker-based run as shown.

Local installation configuration entry:

{
  "mcpServers": {
    "unifi": {
      "command": "/path/to/unifiMCP/.venv/bin/unifi-mcp",
      "env": {
        "UNIFI_HOST": "https://192.168.1.1",
        "UNIFI_USERNAME": "admin",
        "UNIFI_PASSWORD": "your-password",
        "UNIFI_VERIFY_SSL": "false",
        "UNIFI_IS_UNIFI_OS": "true"
      }
    }
  }
}

With Docker configuration entry:

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "UNIFI_HOST=https://192.168.1.1",
        "-e", "UNIFI_USERNAME=admin",
        "-e", "UNIFI_PASSWORD=your-password",
        "-e", "UNIFI_VERIFY_SSL=false",
        "-e", "UNIFI_IS_UNIFI_OS=true",
        "unifi-mcp:latest"
      ]
    }
  }
}

Available tools

get_devices

List all network devices (APs, switches, gateways)

restart_device

Restart a device by MAC address

get_clients

List connected clients

block_client

Block a client from the network

unblock_client

Unblock a previously blocked client

disconnect_client

Force disconnect a client

get_sites

List all configured sites

get_site_health

Get health status for the current site

get_networks

List network configurations

get_device_activity

Get activity for a specific device (clients, traffic)