Unifi MCP Server

Features

Core Capabilities

• Device Management: List, monitor, restart, locate, and upgrade UniFi devices (APs, switches, gateways)
• Network Configuration: Create, update, and delete networks, VLANs, and subnets with DHCP configuration
• Client Management: Query, block, unblock, and reconnect clients
• Firewall Rules: Create, update, and delete firewall rules with traffic filtering
• WiFi/SSID Management: Create and manage wireless networks with WPA2/WPA3, guest networks, and VLAN isolation
• Port Forwarding: Configure port forwarding rules for external access
• DPI Statistics: Deep Packet Inspection analytics for bandwidth usage by application and category
• Multi-Site Support: Work with multiple UniFi sites seamlessly
• Real-time Monitoring: Access device, network, client, and WiFi statistics

Advanced Features

• Redis Caching: Optional Redis-based caching for improved performance (configurable TTL per resource type)
• Webhook Support: Real-time event processing with HMAC signature verification
• Automatic Cache Invalidation: Smart cache invalidation when configuration changes
• Event Handlers: Built-in handlers for device, client, and alert events

Safety & Security

• Confirmation Required: All mutating operations require explicit confirm=True flag
• Dry-Run Mode: Preview changes before applying them with dry_run=True
• Audit Logging: All operations logged to audit.log for compliance
• Input Validation: Comprehensive parameter validation with detailed error messages
• Password Masking: Sensitive data automatically masked in logs
• Type-Safe: Full type hints and Pydantic validation throughout
• Security Scanners: CodeQL, Trivy, Bandit, Safety, and detect-secrets integration

Technical Excellence

• Async Support: Built with async/await for high performance and concurrency
• MCP Protocol: Standard Model Context Protocol for AI agent integration
• Comprehensive Testing: 105 unit tests with detailed coverage reporting
• CI/CD Pipelines: Automated testing, security scanning, and Docker builds
• Multi-Architecture: Docker images for amd64 and arm64

Quick Start

Prerequisites

• Python 3.10 or higher
• A UniFi account at unifi.ui.com
• UniFi API key (obtain from Settings → Control Plane → Integrations)
• Access to UniFi Cloud API or local gateway

Installation

Using uv (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Using pip

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

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Using Docker

# Pull the image
docker pull ghcr.io/enuno/unifi-mcp-server:latest

# Run the container (Cloud API)
docker run -d \
  -e UNIFI_API_KEY=your-api-key \
  -e UNIFI_API_TYPE=cloud \
  -p 3000:3000 \
  ghcr.io/enuno/unifi-mcp-server:latest

# OR run with local gateway proxy
docker run -d \
  -e UNIFI_API_KEY=your-api-key \
  -e UNIFI_API_TYPE=local \
  -e UNIFI_HOST=192.168.1.1 \
  -p 3000:3000 \
  ghcr.io/enuno/unifi-mcp-server:latest