UniFi MCP Server
An MCP (Model Context Protocol) server for Ubiquiti UniFi network devices. This allows AI assistants to interact with UniFi network infrastructure for monitoring, device management, and configuration tasks.
Installation
Option 1: Docker (Recommended)
# 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
# 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
Environment Variables
Configure the following environment variables before running the server:
| Variable | Description | Default | Required |
|---|---|---|---|
UNIFI_HOST | UniFi Controller URL (e.g., https://192.168.1.1) | - | Yes |
UNIFI_USERNAME | UniFi Controller username | - | Yes |
UNIFI_PASSWORD | UniFi Controller password | - | Yes |
UNIFI_SITE | UniFi site name | default | No |
UNIFI_VERIFY_SSL | Verify SSL certificates (true/false) | true | No |
UNIFI_IS_UNIFI_OS | Using UniFi OS device like UDM/UDM Pro (true/false) | false | No |
Example Configuration
# 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"
Usage
Running the Server
With Docker:
# Using Docker Compose (recommended)
docker compose up -d
# Or run directly with Docker
docker run -it --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
Without Docker:
unifi-mcp
Claude Desktop Configuration
Add to your Claude Desktop config file (~/.config/claude/claude_desktop_config.json on Linux or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
Local installation:
{
"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:
{
"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
| Tool | Description |
|---|---|
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 (connected clients, traffic) |
Development
# Run tests
pytest
# Run tests with coverage
pytest --cov=src
# Lint and format
ruff check .
ruff format .
License
MIT