unifi-pro-mcp

# UniFi Pro MCP Server A comprehensive Model Context Protocol (MCP) server for UniFi Network and Protect systems, providing seamless integration with UDM PRO SE and UNVR devices. ## Features - **Multi-Device Support**: Configure multiple UniFi Network and Protect controllers - **Type-Safe APIs**: Full TypeScript implementation with comprehensive type definitions - **Secure Configuration**: Environment-based credential management with no hardcoded values - **NPX Compatible**: Easy installation and execution via npm/npx - **Comprehensive Tools**: Full suite of network management and surveillance tools ### UniFi Network Tools - Get network devices and clients - Site and system information - Device management (restart, block/unblock clients) - Real-time monitoring capabilities ### UniFi Protect Tools - Camera management and configuration - Event and recording retrieval - Motion detection settings - System health monitoring ## Installation ### NPX (Recommended) ```bash npx unifi-pro-mcp ``` ### Global Installation ```bash npm install -g unifi-pro-mcp unifi-pro-mcp ``` ### Local Development ```bash git clone <repository> cd unifi-pro-mcp npm install npm run build npm start ``` ## Configuration ### Environment Variables #### Single Device (Legacy) ```bash # UniFi Network Controller UNIFI_HOST=192.168.1.1 UNIFI_PORT=443 UNIFI_USERNAME=admin UNIFI_PASSWORD=your_password UNIFI_SITE=default UNIFI_SSL=true UNIFI_IGNORE_SSL=false # UniFi Protect Controller UNIFI_PROTECT_HOST=192.168.1.10 UNIFI_PROTECT_PORT=443 UNIFI_PROTECT_USERNAME=admin UNIFI_PROTECT_PASSWORD=your_password UNIFI_PROTECT_SSL=true UNIFI_PROTECT_IGNORE_SSL=false ``` #### Multi-Device (Recommended) ```bash # JSON array of network devices UNIFI_NETWORK_DEVICES='[ { "id": "main", "name": "Main UDM Pro SE", "host": "192.168.1.1", "port": 443, "username": "admin", "password": "your_password", "site": "default", "ssl": true, "ignoreSsl": false }, { "id": "branch", "name": "Branch UDM", "host": "192.168.2.1", "port": 443, "username": "admin", "password": "your_password", "site": "default", "ssl": true, "ignoreSsl": false } ]' # JSON array of protect devices UNIFI_PROTECT_DEVICES='[ { "id": "main", "name": "Main UNVR", "host": "192.168.1.10", "port": 443, "username": "admin", "password": "your_password", "ssl": true, "ignoreSsl": false } ]' # Logging level LOG_LEVEL=INFO ``` ### Configuration File Copy `.env.example` to `.env` and configure your devices: ```bash cp .env.example .env # Edit .env with your device configurations ``` ## Usage with Claude Add the server to your Claude configuration: ```json { "mcpServers": { "unifi-pro": { "command": "npx", "args": ["unifi-pro-mcp"] } } } ``` ## Available Tools ### Network Management #### `network_get_devices` Get all UniFi network devices ```json { "deviceId": "main" } ``` #### `network_get_clients` Get connected network clients ```json { "deviceId": "main", "includeOffline": false } ``` #### `network_restart_device` Restart a network device ```json { "deviceId": "main", "mac": "aa:bb:cc:dd:ee:ff" } ``` #### `network_block_client` Block a client from network access ```json { "deviceId": "main", "mac": "aa:bb:cc:dd:ee:ff" } ``` ### Protect Management #### `protect_get_cameras` Get all cameras from Protect ```json { "deviceId": "main" } ``` #### `protect_get_events` Get security events ```json { "deviceId": "main", "start": 1640995200000, "end": 1641081600000, "limit": 50 } ``` #### `protect_set_recording_mode` Configure camera recording mode ```json { "deviceId": "main", "cameraId": "camera-123", "mode": "motion" } ``` ## Development ### Prerequisites - Node.js >= 18.0.0 - TypeScript >= 5.3.0 ### Build ```bash npm run build ``` ### Development Mode ```bash npm run dev ``` ### Linting & Formatting ```bash npm run lint npm run format ``` ### Testing ```bash npm test ``` ## Security - **No Hardcoded Credentials**: All sensitive data is environment-based - **Input Validation**: Comprehensive validation using Zod schemas - **Secure HTTP Clients**: SSL verification with optional bypass for self-signed certificates - **Sanitized Logging**: Automatic credential redaction in logs ## Architecture ``` src/ ├── index.ts # Main MCP server entry point ├── config/ │ └── ConfigManager.ts # Environment configuration management ├── clients/ │ ├── UniFiNetworkClient.ts # Network controller client │ └── UniFiProtectClient.ts # Protect controller client ├── tools/ │ └── index.ts # MCP tool definitions └── utils/ ├── validation.ts # Input validation and sanitization └── logger.ts # Structured logging ``` ## Supported Devices ### UniFi Network - UDM (UniFi Dream Machine) - UDM Pro - UDM Pro SE - UDR (UniFi Dream Router) - CloudKey Gen2+ ### UniFi Protect - UNVR (UniFi Network Video Recorder) - UNVR Pro - UDM Pro (with Protect) - CloudKey Gen2+ (with Protect) ## Error Handling The server includes comprehensive error handling: - Authentication failures with retry logic - Network timeouts and connection issues - Invalid configuration detection - Input validation with detailed error messages - Graceful degradation for partial system failures ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes with tests 4. Run linting and formatting 5. Submit a pull request ## License MIT License - see LICENSE file for details ## Support For issues and questions: - GitHub Issues: [repository issues](https://github.com/your-repo/issues) - Documentation: [full documentation](https://github.com/your-repo/docs)