A Model Context Protocol (MCP) server that exposes the UniFi Network Controller API, enabling AI agents and applications to interact with UniFi network infrastructure in a standardized way.
Current Stable Release: 0.2.4 (2026-02-19) π
Installation:
pip install unifi-mcp-serverWhat's New in v0.2.4 (Hotfix):
- π¨ Critical Startup Fix (issue #42) -
ImportError: cannot import 'config' from 'agnost'prevented the server from starting for all users, even whenAGNOST_ENABLED=false. The fix moves agnost imports inside the conditional block with graceful error handling. - π Dependency Pin - Excluded broken
agnost==0.1.13from the version range (>=0.1.12,!=0.1.13) - π§ͺ 1,160 Tests Passing - 4 new regression tests covering all agnost import failure scenarios
Previous Release - v0.2.3 (2026-02-18):
- β P1 API bug fixes (QoS audit_action, Site Manager decorator, Topology warnings, Backup client methods)
- β P2 RADIUS & Guest Portal β Complete CRUD (get/update for RADIUS accounts and hotspot packages)
Previous Release - v0.2.2 (2026-02-16):
- π Port Profile Management - 8 new tools for switch port configuration (PoE, VLAN, 802.1X, LLDP-MED)
- π Security Updates - Critical dependency updates (FastMCP 2.14.5, MCP 1.26.0, cryptography 46.0.5)
- π§ͺ 1,068 Tests Passing - 75 new tests, all passing across Python 3.10, 3.11, 3.12
Major Release - v0.2.0 (2026-01-25):
- β¨ 74 MCP Tools - All 7 feature phases complete
- π¦ Published on PyPI - Easy installation with pip/uv
- π QoS Management - Traffic prioritization and bandwidth control (11 tools)
- πΎ Backup & Restore - Automated scheduling and verification (8 tools)
- π Multi-Site Aggregation - Cross-site analytics and management (4 tools)
- π ACL & Traffic Filtering - Advanced traffic control (7 tools)
- π’ Site Management - Multi-site provisioning and VPN (9 tools)
- π RADIUS & Guest Portal - 802.1X authentication (6 tools)
- πΊοΈ Network Topology - Complete topology mapping and visualization (5 tools)
See CHANGELOG.md for complete release notes and VERIFICATION_REPORT.md for detailed verification.
The UniFi MCP Server supports three distinct API modes with different capabilities:
Full feature support - Direct access to your UniFi gateway.
- β All Features Available: Device management, client control, network configuration, firewall rules, WiFi management
- β Real-time Data: Access to live device/client statistics and detailed information
- β Configuration Changes: Create, update, delete networks, VLANs, firewall rules, SSIDs
- π Requirement: Local network access to your UniFi gateway (e.g., 192.168.2.1)
- βοΈ Configuration:
UNIFI_API_TYPE=local+UNIFI_LOCAL_HOST=<gateway-ip>
Limited to aggregate statistics - UniFi cloud API in testing phase.
- β Site Information: List sites with aggregate statistics (device counts, client counts, bandwidth)
β οΈ No Individual Device/Client Access: Cannot query specific devices or clientsβ οΈ No Configuration Changes: Cannot modify networks, firewall rules, or settings- βοΈ Configuration:
UNIFI_API_TYPE=cloud-ea - π Rate Limit: 100 requests/minute
Limited to aggregate statistics - UniFi stable v1 cloud API.
- β Site Information: List sites with aggregate statistics (device counts, client counts, bandwidth)
β οΈ No Individual Device/Client Access: Cannot query specific devices or clientsβ οΈ No Configuration Changes: Cannot modify networks, firewall rules, or settings- βοΈ Configuration:
UNIFI_API_TYPE=cloud-v1 - π Rate Limit: 10,000 requests/minute
π‘ Recommendation: Use Local Gateway API (UNIFI_API_TYPE=local) for full functionality. Cloud APIs are suitable only for high-level monitoring dashboards.
- 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 with detailed analytics
- WiFi/SSID Management: Create and manage wireless networks with WPA2/WPA3, guest networks, and VLAN isolation
- Port Profile Management (v0.2.2): Switch port configuration with PoE, VLAN trunking, 802.1X, LLDP-MED, speed/duplex
- Device Port Overrides (v0.2.2): Per-port configuration on individual switches with smart merge capabilities
- 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
- Firewall Rules: Create, update, and delete firewall rules with advanced traffic filtering
- ACL Management: Layer 3/4 access control lists with rule ordering and priority
- Traffic Matching Lists: IP, MAC, domain, and port-based traffic classification
- Zone-Based Firewall: Modern zone-based security with zone management and zone-to-zone policies
- RADIUS Authentication: 802.1X authentication with RADIUS server configuration
- Guest Portal: Customizable captive portals with hotspot billing and voucher management
- QoS Profiles: Create and manage QoS profiles for traffic prioritization
- Traffic Routes: Time-based routing with schedules and application awareness
- Bandwidth Management: Upload/download limits with guaranteed minimums
- ProAV Mode: Professional audio/video QoS templates
- Reference Profiles: Built-in QoS templates for common applications
- Automated Backups: Schedule backups with cron expressions
- Backup Management: Create, download, restore, and delete backups
- Cloud Sync Tracking: Monitor backup cloud synchronization status
- Checksum Verification: Ensure backup integrity with SHA-256 checksums
- Multiple Backup Types: Network configurations and full system backups
- Site Provisioning: Create, update, and delete UniFi sites
- Site-to-Site VPN: Configure VPN tunnels between sites
- Device Migration: Move devices between sites seamlessly
- Site Health Monitoring: Track site health scores and metrics
- Cross-Site Analytics: Aggregate device and client statistics across locations
- Configuration Export: Export site configurations for backup/documentation
- Topology Discovery: Complete network graph with devices and clients
- Connection Mapping: Port-level device interconnections
- Multi-Format Export: JSON, GraphML (Gephi), and DOT (Graphviz) formats
- Network Depth Analysis: Identify network hierarchy and uplink relationships
- Visual Coordinates: Optional device positioning for diagrams
- 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
- Performance Tracking: Optional agnost.ai integration for monitoring MCP tool performance and usage analytics
- Confirmation Required: All mutating operations require explicit
confirm=Trueflag - Dry-Run Mode: Preview changes before applying them with
dry_run=True - Audit Logging: All operations logged to
audit.logfor 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
- Async Support: Built with async/await for high performance and concurrency
- MCP Protocol: Standard Model Context Protocol for AI agent integration
- Comprehensive Testing: 1,068 unit tests with high coverage, all passing
- CI/CD Pipelines: Automated testing, security scanning, and Docker builds (18 checks)
- Multi-Architecture: Docker images for amd64, arm64, arm/v7 (32-bit ARM), and arm64/v8
- Security Hardened: Updated critical dependencies (FastMCP, MCP SDK, cryptography)
- Quality Metrics: Black formatting, Ruff linting, comprehensive type hints, Pydantic validation
- 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
The UniFi MCP Server is published on PyPI and can be installed with pip or uv:
# Install from PyPI
pip install unifi-mcp-server
# Or using uv (faster)
uv pip install unifi-mcp-server
# Install specific version
pip install unifi-mcp-server==0.2.0After installation, the unifi-mcp-server command will be available globally.
PyPI Package: https://pypi.org/project/unifi-mcp-server/
# Pull the latest release
docker pull ghcr.io/enuno/unifi-mcp-server:0.2.4
# Multi-architecture support: amd64, arm64, arm/v7# 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]"# 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]"The recommended way to run the UniFi MCP Server with full monitoring capabilities:
# 1. Copy and configure environment variables
cp .env.docker.example .env
# Edit .env with your UNIFI_API_KEY and AGNOST_ORG_ID
# 2. Start all services (MCP Server + Redis + MCP Toolbox)
docker-compose up -d
# 3. Check service status
docker-compose ps
# 4. View logs
docker-compose logs -f unifi-mcp
# 5. Access MCP Toolbox dashboard
open http://localhost:8080
# 6. Stop all services
docker-compose downIncluded Services:
- UniFi MCP Server: Main MCP server with 77 tools (69 functional, 8 deprecated)
- MCP Toolbox: Web-based analytics dashboard (port 8080)
- Redis: High-performance caching layer
See MCP_TOOLBOX.md for detailed Toolbox documentation.
For standalone Docker usage (not with MCP clients):
# Pull the image
docker pull ghcr.io/enuno/unifi-mcp-server:latest
# Run the container in background (Cloud API)
# Note: -i flag keeps stdin open for STDIO transport
docker run -i -d \
--name unifi-mcp \
-e UNIFI_API_KEY=your-api-key \
-e UNIFI_API_TYPE=cloud \
ghcr.io/enuno/unifi-mcp-server:latest
# OR run with local gateway proxy
docker run -i -d \
--name unifi-mcp \
-e UNIFI_API_KEY=your-api-key \
-e UNIFI_API_TYPE=local \
-e UNIFI_HOST=192.168.2.1 \
ghcr.io/enuno/unifi-mcp-server:latest
# Check container status
docker ps --filter name=unifi-mcp
# View logs
docker logs unifi-mcp
# Stop and remove
docker rm -f unifi-mcpNote: For MCP client integration (Claude Desktop, etc.), see the Usage section below for the correct configuration without -d flag.
- Python 3.10+: Required for running the server
- Git: For cloning the repository
- uv (recommended) or pip: For dependency management
- Docker (optional): For containerized builds
- Node.js & npm (optional): For npm package publishing
git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-serverUsing uv (Recommended):
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create virtual environment
uv venv
# Activate virtual environment
source .venv/bin/activate # Linux/macOS
# Or on Windows: .venv\Scripts\activate
# Install development dependencies
uv pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msgUsing pip:
# Create virtual environment
python -m venv .venv
# Activate virtual environment
source .venv/bin/activate # Linux/macOS
# Or on Windows: .venv\Scripts\activate
# Upgrade pip
pip install --upgrade pip
# Install development dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msg# Copy example configuration
cp .env.example .env
# Edit .env with your UniFi credentials
# Required: UNIFI_API_KEY
# Recommended: UNIFI_API_TYPE=local, UNIFI_LOCAL_HOST=<gateway-ip># Run all unit tests
pytest tests/unit/ -v
# Run with coverage report
pytest tests/unit/ --cov=src --cov-report=html --cov-report=term-missing
# View coverage report
open htmlcov/index.html # macOS
# Or: xdg-open htmlcov/index.html # Linux# Development mode with MCP Inspector
uv run mcp dev src/main.py
# Production mode
uv run python -m src.main
# The MCP Inspector will be available at http://localhost:5173# Install build tools
uv pip install build
# Build wheel and source distribution
python -m build
# Output: dist/unifi_mcp_server-0.2.0-py3-none-any.whl
# dist/unifi_mcp_server-0.2.0.tar.gz# Build for current architecture
docker build -t unifi-mcp-server:0.2.0 .
# Build multi-architecture (requires buildx)
docker buildx create --use
docker buildx build \
--platform linux/amd64,linux/arm64,linux/arm/v7 \
-t ghcr.io/enuno/unifi-mcp-server:0.2.0 \
--push .
# Test the image
docker run -i --rm \
-e UNIFI_API_KEY=your-key \
-e UNIFI_API_TYPE=cloud \
unifi-mcp-server:0.2.0# Install twine
uv pip install twine
# Check distribution
twine check dist/*
# Upload to PyPI (requires PyPI account and token)
twine upload dist/*
# Or upload to Test PyPI first
twine upload --repository testpypi dist/*# Ensure package.json is up to date
cat package.json
# Login to npm (if not already)
npm login
# Publish package
npm publish --access public
# Verify publication
npm view unifi-mcp-server# Install mcp-publisher
brew install mcp-publisher
# Or: curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/
# Authenticate with GitHub (for io.github.enuno namespace)
mcp-publisher login github
# Publish to registry (requires npm package published first)
mcp-publisher publish
# Verify
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.enuno/unifi-mcp-server"See docs/RELEASE_PROCESS.md for the complete release workflow, including automated GitHub Actions, manual PyPI/npm publishing, and MCP registry submission.
- Log in to UniFi Site Manager
- Navigate to Settings β Control Plane β Integrations
- Click Create API Key
- Save the key immediately - it's only shown once!
- Store it securely in your
.envfile
Create a .env file in the project root:
# Required: Your UniFi API Key
UNIFI_API_KEY=your-api-key-here
# API Mode Selection (choose one):
# - 'local': Full access via local gateway (RECOMMENDED)
# - 'cloud-ea': Early Access cloud API (limited to statistics)
# - 'cloud-v1': Stable v1 cloud API (limited to statistics)
UNIFI_API_TYPE=local
# Local Gateway Configuration (for UNIFI_API_TYPE=local)
UNIFI_LOCAL_HOST=192.168.2.1
UNIFI_LOCAL_PORT=443
UNIFI_LOCAL_VERIFY_SSL=false
# Cloud API Configuration (for cloud-ea or cloud-v1)
# UNIFI_CLOUD_API_URL=https://api.ui.com
# Optional settings
UNIFI_DEFAULT_SITE=default
# Redis caching (optional - improves performance)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
# REDIS_PASSWORD=your-password # If Redis requires authentication
# Webhook support (optional - for real-time events)
WEBHOOK_SECRET=your-webhook-secret-here
# Performance tracking with agnost.ai (optional - for analytics)
# Get your Organization ID from https://app.agnost.ai
# AGNOST_ENABLED=true
# AGNOST_ORG_ID=your-organization-id-here
# AGNOST_ENDPOINT=https://api.agnost.ai
# AGNOST_DISABLE_INPUT=false # Set to true to disable input tracking
# AGNOST_DISABLE_OUTPUT=false # Set to true to disable output trackingSee .env.example for all available options.
# Development mode with MCP Inspector
uv run mcp dev src/main.py
# Production mode
uv run python src/main.pyThe MCP Inspector will be available at http://localhost:5173 for interactive testing.
Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
After installing via pip install unifi-mcp-server:
{
"mcpServers": {
"unifi": {
"command": "unifi-mcp-server",
"env": {
"UNIFI_API_KEY": "your-api-key-here",
"UNIFI_API_TYPE": "local",
"UNIFI_LOCAL_HOST": "192.168.2.1"
}
}
}
}For cloud API access, use:
{
"mcpServers": {
"unifi": {
"command": "unifi-mcp-server",
"env": {
"UNIFI_API_KEY": "your-api-key-here",
"UNIFI_API_TYPE": "cloud-v1"
}
}
}
}{
"mcpServers": {
"unifi": {
"command": "uvx",
"args": ["unifi-mcp-server"],
"env": {
"UNIFI_API_KEY": "your-api-key-here",
"UNIFI_API_TYPE": "local",
"UNIFI_LOCAL_HOST": "192.168.2.1"
}
}
}
}{
"mcpServers": {
"unifi": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"UNIFI_API_KEY=your-api-key-here",
"-e",
"UNIFI_API_TYPE=cloud",
"ghcr.io/enuno/unifi-mcp-server:latest"
]
}
}
}Important: Do NOT use -d (detached mode) in MCP client configurations. The MCP client needs to maintain a persistent stdin/stdout connection to the container.
Add to your Cursor MCP configuration (mcp.json via "View: Open MCP Settings β New MCP Server"):
After installing via pip install unifi-mcp-server:
{
"mcpServers": {
"unifi-mcp": {
"command": "unifi-mcp-server",
"env": {
"UNIFI_API_KEY": "your-api-key-here",
"UNIFI_API_TYPE": "local",
"UNIFI_LOCAL_HOST": "192.168.2.1",
"UNIFI_LOCAL_VERIFY_SSL": "false"
},
"disabled": false
}
}
}{
"mcpServers": {
"unifi-mcp": {
"command": "uvx",
"args": ["unifi-mcp-server"],
"env": {
"UNIFI_API_KEY": "your-api-key-here",
"UNIFI_API_TYPE": "local",
"UNIFI_LOCAL_HOST": "192.168.2.1"
},
"disabled": false
}
}
}{
"mcpServers": {
"unifi-mcp": {
"command": "docker"