Files

Build and Push Docker Image / build (push) Failing after 12s

Details

Initial implementation of UniFi MCP Light server

Implements Hybrid MCP Light pattern with:
- 4 specific tools: list_clients, list_devices, get_system_info, get_network_health
- Meta tools: tool_index, api_call (raw API pass-through)
- API documentation resource at unifi://api-reference
- Starlette wrapper with /health endpoint
- Write protection (UNIFI_ALLOW_WRITES env var)
- UniFi OS auto-detection (proxy vs direct paths)
- Docker multi-stage build
- Gitea CI workflow

Closes #1, #2, #3, #4, #5, #7

2026-01-02 02:21:10 +00:00

3.9 KiB

Raw Permalink Blame History

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:

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

See IMPLEMENTATION.md for technical details.

License

MIT

3.9 KiB Raw Permalink Blame History