# 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)

```bash
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

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

### Python / UV

```bash
# 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`:

```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](IMPLEMENTATION.md) for technical details.

## License

MIT