UniFi MCP Server

# 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