# UniFi MCP Server

A Model Context Protocol (MCP) server for comprehensive UniFi Network Management via the UniFi Cloud API. This server enables AI assistants like Claude to manage your UniFi infrastructure through natural language.

## Features

- **UniFi Cloud API Integration** - Full access to api.ui.com for remote management
- **OAuth 2.0 Authentication** - Secure access with PKCE support for Claude Desktop, Claude Mobile, ChatGPT, and more
- **Multi-Transport Support** - SSE and Streamable HTTP for flexible deployment
- **Complete UniFi Ecosystem** - Network, Protect (cameras), and Access (doors) management
- **Production Ready** - Docker support, Redis for token storage, Coolify/VPS deployment

## Quick Start

### 1. Get Your UniFi Cloud API Key

1. Go to [UniFi Site Manager](https://unifi.ui.com)
2. Navigate to API section from the left navigation
3. Click "Create API Key"
4. Copy the generated key

### 2. Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/unifi-mcp-server.git
cd unifi-mcp-server

# Install dependencies
npm install

# Create environment file
cp .env.example .env
```

### 3. Configuration

Edit `.env` with your settings:

```env
# Required: Your UniFi Cloud API Key
UNIFI_API_KEY=zjWD6zwI55loIpMLLcjDDvRTCuVnVyHA2

# Server settings
PORT=3000
BASE_URL=https://your-domain.com

# OAuth password for authorization (optional but recommended)
OAUTH_PASSWORD=your_secure_password

# API Key for direct access (optional)
API_KEY=your_api_key
```

### 4. Run the Server

**Development (stdio mode for Claude Desktop):**
```bash
npm run dev
```

**Production (HTTP server with OAuth):**
```bash
npm run start:http
```

**Docker:**
```bash
docker-compose up -d
```

## Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "unifi": {
      "command": "node",
      "args": ["/path/to/unifi-mcp-server/src/index.js"],
      "env": {
        "UNIFI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Remote Access (Claude Mobile / ChatGPT)

For remote access, deploy the HTTP server and connect via OAuth:

1. Deploy to your VPS or Coolify
2. Configure your domain with HTTPS
3. Connect using the OAuth flow:
   - Server URL: `https://your-domain.com`
   - Client ID: `claude-mobile` or `chatgpt`
   - Scope: `unifi-api`

## Available Tools

### Network & System
| Tool | Description |
|------|-------------|
| `unifi_health` | Check UniFi Cloud API connectivity |
| `get_system_status` | Comprehensive system status overview |
| `list_hosts` | List all UniFi OS consoles |
| `list_sites` | List all network sites |
| `get_isp_metrics` | Get ISP performance metrics |

### Devices
| Tool | Description |
|------|-------------|
| `list_all_devices` | List all UniFi devices |
| `get_device` | Get device details |
| `locate_device` | Flash LEDs to locate a device |
| `restart_device` | Restart a device |
| `find_device_by_mac` | Search by MAC address |
| `get_offline_devices` | List offline devices |

### Clients
| Tool | Description |
|------|-------------|
| `list_all_clients` | List all connected clients |
| `block_client` | Block a client from network |
| `unblock_client` | Unblock a client |
| `reconnect_client` | Force reconnect a client |
| `find_client_by_name` | Search clients by name |
| `get_client_bandwidth_summary` | Bandwidth usage analysis |

### UniFi Protect (Cameras)
| Tool | Description |
|------|-------------|
| `list_cameras` | List all cameras |
| `get_camera` | Get camera details |
| `set_camera_privacy` | Toggle privacy mode |
| `set_camera_recording` | Set recording mode |

### UniFi Access (Doors)
| Tool | Description |
|------|-------------|
| `list_doors` | List all access doors |
| `unlock_door` | Temporarily unlock a door |
| `lock_door` | Lock a door |

## Example Usage

Once connected, you can use natural language:

- "Show me the status of my UniFi network"
- "List all offline devices"
- "Who's using the most bandwidth?"
- "Block the device with MAC XX:XX:XX:XX:XX:XX"
- "Unlock the front door for 10 seconds"
- "Turn on privacy mode for the garage camera"

## Deployment

### Coolify

1. Create new application from Git repository
2. Set environment variables in Coolify dashboard
3. Configure your domain with HTTPS
4. Deploy!

### Docker Compose

```bash
# Set environment variables
export UNIFI_API_KEY=your_key
export OAUTH_PASSWORD=your_password
export BASE_URL=https://your-domain.com

# Start services
docker-compose up -d
```

### Manual VPS

```bash
# Install Node.js 20+
# Clone repository
# Install dependencies: npm install
# Set up systemd service or PM2
# Configure reverse proxy (nginx/caddy) with SSL
```

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /health` | Health check |
| `GET /status` | Server status |
| `GET /.well-known/oauth-authorization-server` | OAuth discovery |
| `GET /oauth/authorize` | OAuth authorization |
| `POST /oauth/token` | Token exchange |
| `GET /sse` | SSE transport |
| `POST /mcp/messages` | MCP messages (authenticated) |

## Security

- **HTTPS Required** - Always use HTTPS in production
- **OAuth 2.0 + PKCE** - Secure authorization flow
- **API Key Authentication** - Alternative for server-to-server
- **Password Protection** - Optional OAuth authorization password
- **Redis Token Storage** - Secure token management with TTL

## Troubleshooting

### API Key Issues
```bash
# Test your API key
curl -H "X-API-Key: YOUR_KEY" https://api.ui.com/v1/hosts
```

### OAuth Issues
- Check `OAUTH_PASSWORD` is set correctly
- Verify `BASE_URL` uses HTTPS
- Ensure redirect URIs match client configuration

### Connection Issues
- Verify UniFi Cloud API is accessible
- Check firewall rules for port 3000
- Review container logs: `docker-compose logs -f`

## License

MIT License - See LICENSE file for details.

## Contributing

Pull requests welcome! Please ensure:
- Tests pass
- Documentation updated
- Code follows existing style