# UniFi MCP Server

Model Context Protocol (MCP) server for managing Ubiquiti UniFi/UDM Pro devices through Claude Desktop and other MCP clients.

## Features

- List and query UniFi devices (APs, switches, gateways)
- View client/station information
- Get network and VLAN configurations
- View WLAN/WiFi configurations
- Monitor events and alarms
- Get system information and health status

## Installation

```bash
pnpm install
pnpm build
```

## Configuration

### Environment Variables

Create or update `~/.env` with the following:

#### Private API Mode (Default)

```bash
# UniFi Controller Configuration
UNIFI_UDM_URL=https://192.168.1.1
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your-password
UNIFI_SITE_ID=default  # Optional, will use default site if not set
UNIFI_API_MODE=private  # Optional, defaults to private
UNIFI_VERIFY_SSL=false  # Set to true for production (requires valid SSL cert)
```

#### Official API Mode

```bash
# UniFi Controller Configuration
UNIFI_UDM_URL=https://192.168.1.1
UNIFI_API_KEY=your-api-key
UNIFI_SITE_ID=default  # Optional, will use default site if not set
UNIFI_API_MODE=official
UNIFI_VERIFY_SSL=false  # Set to true for production (requires valid SSL cert)
```

### Getting API Credentials

#### Official API (API Key)

1. Access your UniFi Network app
2. Navigate to **Settings → Control Plane → Integrations**
3. Generate an API key
4. Use the API key in `UNIFI_API_KEY` environment variable

#### Private API (Username/Password)

- Use your UniFi Controller admin username and password
- Private API uses cookie-based session authentication

## Claude Desktop Integration

Add to your Claude Desktop config file:

```json
{
  "mcpServers": {
    "unifi": {
      "command": "node",
      "args": ["/path/to/proxmox/mcp-unifi/dist/index.js"]
    }
  }
}
```

### Config File Locations

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

## Available Tools

### Site Management

- `unifi_list_sites` - List all sites
- `unifi_get_site_stats` - Get site statistics

### Device Management

- `unifi_list_devices` - List all devices
- `unifi_get_device` - Get device by MAC address
- `unifi_get_device_stats` - Get device statistics

### Client Management

- `unifi_list_clients` - List all active clients
- `unifi_get_client` - Get client by ID or MAC address

### Network Management

- `unifi_list_networks` - List all networks/VLANs
- `unifi_get_network` - Get network by ID

### WLAN Management

- `unifi_list_wlans` - List all WLAN configurations
- `unifi_get_wlan` - Get WLAN by ID

### Events & Monitoring

- `unifi_list_events` - List events
- `unifi_list_alarms` - List alarms

### System Operations

- `unifi_get_system_info` - Get system information
- `unifi_get_health` - Get site health status

## Usage Examples

Once configured, you can ask Claude Desktop:

- "List all devices in my UniFi network"
- "Show me the active clients"
- "What are the network configurations?"
- "Get system information"
- "Show me recent events"
- "What's the health status of the site?"

## Troubleshooting

### Connection Errors

- Verify `UNIFI_UDM_URL` is correct (IP address or hostname)
- Check that the UniFi Controller is running and accessible
- If using self-signed certificates, ensure `UNIFI_VERIFY_SSL=false`

### Authentication Errors

- For Private API: Verify `UNIFI_USERNAME` and `UNIFI_PASSWORD` are correct
- For Official API: Verify `UNIFI_API_KEY` is correct and valid
- Check that the API mode matches your credentials

### Device/Client Not Found

- Verify IDs/MAC addresses are correct
- Check that `siteId` matches the device's site (if provided)
- Ensure the device/client is adopted and online

## License

MIT