UniFi MCP Light

A Hybrid MCP Light Server for UniFi Network Controller following the minimal-surface-area pattern with raw API pass-through.

Features

• 4 Specific Tools: Common read operations for clients, devices, system info, and health
• Raw API Pass-through: Access any UniFi API endpoint via unifi_api_call
• Embedded Documentation: API reference available as MCP Resource
• Write Protection: Mutations disabled by default, enable with UNIFI_ALLOW_WRITES=true
• UniFi OS Support: Auto-detects Cloud Gateway, UDM, and standalone controllers
• Health Endpoint: /health for Docker health checks

Quick Start

Docker (Recommended)

docker run -d \
  -p 8100:8000 \
  -e UNIFI_HOST=192.168.1.1 \
  -e UNIFI_USERNAME=admin \
  -e UNIFI_PASSWORD=your_password \
  gitea.ext.ben.io/b3nw/unifi-mcp-light:latest

Docker Compose

cp .env.example .env
# Edit .env with your UniFi credentials
docker-compose up -d

Python / UV

# Install UV
curl -fsSL https://astral.sh/uv/install.sh | bash

# Clone and install
git clone gitea@git.local.ben.io:b3nw/unifi-mcp-light.git
cd unifi-mcp-light
uv venv && source .venv/bin/activate
uv pip install -e .

# Configure
cp .env.example .env
# Edit .env with your credentials

# Run
python server.py

Configuration

Variable	Description	Default
UNIFI_HOST	Controller IP/hostname	required
UNIFI_USERNAME	Admin username	required
UNIFI_PASSWORD	Admin password	required
UNIFI_PORT	HTTPS port	443
UNIFI_SITE	Site name	default
UNIFI_VERIFY_SSL	Verify SSL certificate	false
UNIFI_ALLOW_WRITES	Enable write operations	false
PORT	Host port (docker-compose)	8100

Tools

Specific Tools (4)

Tool	Description
unifi_list_clients	List connected network clients (phones, laptops, IoT)
unifi_list_devices	List UniFi devices (APs, switches, gateways)
unifi_get_system_info	Get controller version and configuration
unifi_get_network_health	Get health status per subsystem (WAN, LAN, WLAN)

Meta Tools

Tool	Description
unifi_tool_index	Get catalog of all available tools with schemas
unifi_api_call	Raw API pass-through (the "escape hatch")

Resources

URI	Description
unifi://api-reference	Curated UniFi API documentation

Usage Examples

List Connected Clients

Use the unifi_list_clients tool

Raw API Call (Read)

Use unifi_api_call with:
- endpoint: /api/s/default/stat/event
- method: GET

Raw API Call (Write - requires UNIFI_ALLOW_WRITES=true)

Use unifi_api_call with:
- endpoint: /api/s/default/cmd/stamgr
- method: POST
- params: {"cmd": "block-sta", "mac": "aa:bb:cc:dd:ee:ff"}

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "UNIFI_HOST=192.168.1.1",
        "-e", "UNIFI_USERNAME=admin",
        "-e", "UNIFI_PASSWORD=your_password",
        "gitea.ext.ben.io/b3nw/unifi-mcp-light:latest"
      ]
    }
  }
}

Security

• Write operations are disabled by default
• Set UNIFI_ALLOW_WRITES=true only when needed
• Use read-only credentials when possible
• Don't expose the server to the internet without authentication

Architecture

This server follows the Hybrid MCP Light pattern:

1. Minimal Surface Area: Only 4 specific tools for common operations
2. Escape Hatch: Raw API pass-through for any other operation
3. Embedded Documentation: API docs as MCP Resource
4. Starlette Wrapper: Health checks for container orchestration

See IMPLEMENTATION.md for technical details.

License

MIT