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)

npx unifi-pro-mcp

Global Installation

npm install -g unifi-pro-mcp
unifi-pro-mcp

Local Development

git clone <repository>
cd unifi-pro-mcp
npm install
npm run build
npm start

Configuration

Environment Variables

Single Device (Legacy)

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

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

cp .env.example .env
# Edit .env with your device configurations

Usage with Claude

Add the server to your Claude configuration:

{
  "mcpServers": {
    "unifi-pro": {
      "command": "npx",
      "args": ["unifi-pro-mcp"]
    }
  }
}

Available Tools

Network Management

network_get_devices

Get all UniFi network devices

{
  "deviceId": "main"
}

network_get_clients

Get connected network clients

{
  "deviceId": "main",
  "includeOffline": false
}

network_restart_device

Restart a network device

{
  "deviceId": "main",
  "mac": "aa:bb:cc:dd:ee:ff"
}

network_block_client

Block a client from network access

{
  "deviceId": "main",
  "mac": "aa:bb:cc:dd:ee:ff"
}

Protect Management

protect_get_cameras

Get all cameras from Protect

{
  "deviceId": "main"
}

protect_get_events

Get security events

{
  "deviceId": "main",
  "start": 1640995200000,
  "end": 1641081600000,
  "limit": 50
}

protect_set_recording_mode

Configure camera recording mode

{
  "deviceId": "main",
  "cameraId": "camera-123",
  "mode": "motion"
}

Development

Prerequisites

• Node.js >= 18.0.0
• TypeScript >= 5.3.0

Build

npm run build

Development Mode

npm run dev

Linting & Formatting

npm run lint
npm run format

Testing

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
• Documentation: full documentation