UniFi MCP Server

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.

📋 Version Notice

Current Stable Release: v0.2.4 (2026-02-19) 🎉

Installation:

pip install unifi-mcp-server

What'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 when AGNOST_ENABLED=false. The fix moves agnost imports inside the conditional block with graceful error handling.
📌 Dependency Pin - Excluded broken agnost==0.1.13 from 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.

🌐 API Mode Support

The UniFi MCP Server supports three distinct API modes with different capabilities:

Local Gateway API (Recommended) ✅

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>

Cloud Early Access API ⚠️

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

Cloud V1 API ⚠️

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.

Features

Core Network Management

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

Security & Firewall (v0.2.0)

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

Quality of Service (v0.2.0)

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

Backup & Operations (v0.2.0)

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

Multi-Site Management (v0.2.0)

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

Network Topology (v0.2.0)

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

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
Performance Tracking: Optional agnost.ai integration for monitoring MCP tool performance and usage analytics

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

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 PyPI (Recommended)

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.0

After installation, the unifi-mcp-server command will be available globally.

PyPI Package: https://pypi.org/project/unifi-mcp-server/

Using Docker (Alternative)

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

# Multi-architecture support: amd64, arm64, arm/v7

Build from Source (Development)

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 Compose (Recommended for Production)

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 down

Included 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.

Using Docker (Standalone)

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-mcp

Note: For MCP client integration (Claude Desktop, etc.), see the Usage section below for the correct configuration without -d flag.

Build from Source

Prerequisites

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

Development Build

1. Clone the Repository

git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server

2. Set Up Development Environment

Using 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-msg

Using 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

3. Configure Environment

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

4. Run Tests

# 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

5. Run the Server

# 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

Production Build

Build Python Package

# 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 Docker Image

# 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

Publishing

Publish to PyPI

# 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/*

Publish to npm (Metadata Wrapper)

# 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

Publish to MCP Registry

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

Release Process

See docs/RELEASE_PROCESS.md for the complete release workflow, including automated GitHub Actions, manual PyPI/npm publishing, and MCP registry submission.

Configuration

Obtaining Your API Key

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 .env file

Configuration File

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 tracking

See .env.example for all available options.

Running the Server

# Development mode with MCP Inspector
uv run mcp dev src/main.py

# Production mode
uv run python src/main.py

The MCP Inspector will be available at http://localhost:5173 for interactive testing.

Usage

With Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Using PyPI Package (Recommended)

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"
      }
    }
  }
}

Option 2: Using uv with PyPI Package

{
  "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"
      }
    }
  }
}

Option 3: Using Docker

{
  "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.

With Cursor

Add to your Cursor MCP configuration (mcp.json via "View: Open MCP Settings → New MCP Server"):

Option 1: Using PyPI Package (Recommended)

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
    }
  }
}

Option 2: Using uv with PyPI Package

{
  "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
    }
  }
}

Option 3: Using Docker

{
  "mcpServers": {
    "unifi-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--name", "unifi-mcp-server",
        "-e", "UNIFI_API_KEY=your_unifi_api_key_here",
        "-e", "UNIFI_API_TYPE=local",
        "-e", "UNIFI_LOCAL_HOST=192.168.2.1",
        "-e", "UNIFI_LOCAL_VERIFY_SSL=false",
        "ghcr.io/enuno/unifi-mcp-server:latest"
      ],
      "disabled": false
    }
  }
}

Configuration Notes:

Replace UNIFI_API_KEY with your actual UniFi API key
For local gateway access, set UNIFI_API_TYPE=local and provide UNIFI_LOCAL_HOST
For cloud API access, use UNIFI_API_TYPE=cloud-v1 or cloud-ea
After saving, restart Cursor to activate the server
Invoke tools in the Chat sidebar (e.g., "List my UniFi devices")

With Other MCP Clients

The UniFi MCP Server works with any MCP-compatible client. Here are generic configuration patterns:

Using the Installed Command

After installing from PyPI (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"
      }
    }
  }
}

Using uvx (Run from PyPI without installation)

{
  "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"
      }
    }
  }
}

Using Python Module Directly

{
  "mcpServers": {
    "unifi": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "env": {
        "UNIFI_API_KEY": "your-api-key-here",
        "UNIFI_API_TYPE": "local",
        "UNIFI_LOCAL_HOST": "192.168.2.1"
      }
    }
  }
}

Environment Variables (All Clients):

UNIFI_API_KEY (required): Your UniFi API key from unifi.ui.com
UNIFI_API_TYPE (required): local, cloud-v1, or cloud-ea
For Local Gateway API:
- UNIFI_LOCAL_HOST: Gateway IP (e.g., 192.168.2.1)
- UNIFI_LOCAL_PORT: Gateway port (default: 443)
- UNIFI_LOCAL_VERIFY_SSL: SSL verification (default: false)
For Cloud APIs:
- UNIFI_CLOUD_API_URL: Cloud API URL (default: https://api.ui.com)
- UNIFI_DEFAULT_SITE: Default site ID (default: default)

Programmatic Usage

from mcp import MCP
import asyncio

async def main():
    mcp = MCP("unifi-mcp-server")

    # List all devices
    devices = await mcp.call_tool("list_devices", {
        "site_id": "default"
    })

    for device in devices:
        print(f"{device['name']}: {device['status']}")

    # Get network information via resource
    networks = await mcp.read_resource("sites://default/networks")
    print(f"Networks: {len(networks)}")

    # Create a guest WiFi network with VLAN isolation
    wifi = await mcp.call_tool("create_wlan", {
        "site_id": "default",
        "name": "Guest WiFi",
        "security": "wpapsk",
        "password": "GuestPass123!",
        "is_guest": True,
        "vlan_id": 100,
        "confirm": True  # Required for safety
    })
    print(f"Created WiFi: {wifi['name']}")

    # Get DPI statistics for top bandwidth users
    top_apps = await mcp.call_tool("list_top_applications", {
        "site_id": "default",
        "limit": 5,
        "time_range": "24h"
    })

    for app in top_apps:
        gb = app['total_bytes'] / 1024**3
        print(f"{app['application']}: {gb:.2f} GB")

    # Create Zone-Based Firewall zones (UniFi Network 9.0+)
    lan_zone = await mcp.call_tool("create_firewall_zone", {
        "site_id": "default",
        "name": "LAN",
        "description": "Trusted local network",
        "confirm": True
    })

    iot_zone = await mcp.call_tool("create_firewall_zone", {
        "site_id": "default",
        "name": "IoT",
        "description": "Internet of Things devices",
        "confirm": True
    })

    # Set zone-to-zone policy (LAN can access IoT, but IoT cannot access LAN)
    await mcp.call_tool("update_zbf_policy", {
        "site_id": "default",
        "source_zone_id": lan_zone["_id"],
        "destination_zone_id": iot_zone["_id"],
        "action": "accept",
        "confirm": True
    })

asyncio.run(main())

API Documentation

See API.md for complete API documentation, including:

Available MCP tools
Resource URI schemes
Request/response formats
Error handling
Examples

Development

Setup Development Environment

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

# Install pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msg

Running Tests

# Run all tests
pytest tests/unit/

# Run with coverage report
pytest tests/unit/ --cov=src --cov-report=html --cov-report=term-missing

# Run specific test file
pytest tests/unit/test_zbf_tools.py -v

# Run tests for new v0.2.0 features
pytest tests/unit/test_new_models.py tests/unit/test_zbf_tools.py tests/unit/test_traffic_flow_tools.py

# Run only unit tests (fast)
pytest -m unit

# Run only integration tests (requires UniFi controller)
pytest -m integration

Current Test Coverage (v0.2.0):

Overall: 78.18% (990 tests passing)
Total Statements: 6,105 statements, 4,865 covered
Branch Coverage: 75.03%

By Module Category:

Models: 98%+ coverage (Excellent)
Core Tools: 90-100% coverage (Excellent)
v0.2.0 Features: 70-96% coverage (Good to Excellent)
- Topology: 95.83% (29 tests)
- Backup & Restore: 86.32% (10 tests)
- Multi-Site Aggregation: 92.95% (10 tests)
- QoS: 82.43% (46 tests)
- RADIUS: 69.77% (17 tests)
Utilities: 90%+ coverage (Excellent)

Top Coverage Performers (>95%):

clients.py: 98.72%
devices.py: 98.44%
device_control.py: 99.10%
topology.py: 95.83% ⭐ (v0.2.0)
vouchers.py: 96.36%
firewall.py: 96.11%

See VERIFICATION_REPORT.md for complete coverage details and TESTING_PLAN.md for testing strategy.

Code Quality

# Format code
black src/ tests/
isort src/ tests/

# Lint code
ruff check src/ tests/ --fix

# Type check
mypy src/

# Run all pre-commit checks
pre-commit run --all-files

Testing with MCP Inspector

# Start development server with inspector
uv run mcp dev src/main.py

# Open http://localhost:5173 in your browser

Project Structure

unifi-mcp-server/
├── .github/
│   └── workflows/          # CI/CD pipelines (CI, security, release)
├── .claude/
│   └── commands/          # Custom slash commands for development
├── src/
│   ├── main.py            # MCP server entry point (77 tools registered)
│   ├── cache.py           # Redis caching implementation
│   ├── config/            # Configuration management
│   ├── api/               # UniFi API client with rate limiting
│   ├── models/            # Pydantic data models
│   │   └── zbf.py         # Zone-Based Firewall models
│   ├── tools/             # MCP tool definitions
│   │   ├── clients.py     # Client query tools
│   │   ├── devices.py     # Device query tools
│   │   ├── networks.py    # Network query tools
│   │   ├── sites.py       # Site query tools
│   │   ├── firewall.py    # Firewall management (Phase 4)
│   │   ├── firewall_zones.py  # Zone-Based Firewall zone management (v0.1.4)
│   │   ├── zbf_matrix.py  # Zone-Based Firewall policy matrix (v0.1.4)
│   │   ├── network_config.py  # Network configuration (Phase 4)
│   │   ├── device_control.py  # Device control (Phase 4)
│   │   ├── client_management.py  # Client management (Phase 4)
│   │   ├── wifi.py        # WiFi/SSID management (Phase 5)
│   │   ├── port_forwarding.py  # Port forwarding (Phase 5)
│   │   └── dpi.py         # DPI statistics (Phase 5)
│   ├── resources/         # MCP resource definitions
│   ├── webhooks/          # Webhook receiver and handlers (Phase 5)
│   └── utils/             # Utility functions and validators
├── tests/
│   ├── unit/              # Unit tests (213 tests, 37% coverage)
│   ├── integration/       # Integration tests (planned)
│   └── performance/       # Performance benchmarks (planned)
├── docs/                  # Additional documentation
│   └── AI-Coding/         # AI coding guidelines
├── .env.example           # Environment variable template
├── pyproject.toml         # Project configuration
├── README.md              # This file
├── API.md                 # Complete API documentation
├── ZBF_STATUS.md          # Zone-Based Firewall implementation status
├── TESTING_PLAN.md        # Testing strategy and roadmap
├── DEVELOPMENT_PLAN.md    # Development roadmap
├── CONTRIBUTING.md        # Contribution guidelines
├── SECURITY.md            # Security policy and best practices
├── AGENTS.md              # AI agent guidelines
└── LICENSE                # Apache 2.0 License

Contributing

We welcome contributions from both human developers and AI coding assistants! Please see:

CONTRIBUTING.md - Contribution guidelines
AGENTS.md - AI agent-specific guidelines
AI_CODING_ASSISTANT.md - AI coding standards
AI_GIT_PRACTICES.md - AI Git practices

Quick Contribution Guide

Fork the repository
Create a feature branch: git checkout -b feature/your-feature-name
Make your changes
Run tests and linting: pytest && pre-commit run --all-files
Commit with conventional commits: feat: add new feature
Push and create a pull request

Automated Bug Reports

Found a bug? Issues with [Bug] in the title are automatically analyzed by our AI bug handler:

Instant Response: Get immediate feedback on your bug report
Smart Analysis: AI determines if it's a real bug or usage issue
Auto-Fix: Simple bugs may be automatically fixed with a PR
Helpful Guidance: Usage issues receive documentation and examples

See CONTRIBUTING.md for more details.

Security

Security is a top priority. Please see SECURITY.md for:

Reporting vulnerabilities
Security best practices
Supported versions

Never commit credentials or sensitive data!

Roadmap

Version 0.2.0 (Current - Complete ✅ 2026-01-25)

All 7 Feature Phases Complete - 74 MCP Tools

Phase 3: Read-Only Operations (16 tools)

Device management (list, details, statistics, search by type)
Client management (list, details, statistics, search)
Network information (details, VLANs, subnets, statistics)
Site management (list, details, statistics)
MCP resources (sites, devices, clients, networks)

Phase 4: Mutating Operations with Safety (13 tools)

Firewall rule management (create, update, delete)
Network configuration (create, update, delete networks/VLANs)
Device control (restart, locate, upgrade)
Client management (block, unblock, reconnect)
Safety mechanisms (confirmation, dry-run, audit logging)

Phase 5: Advanced Features (11 tools)

WiFi/SSID management (create, update, delete, statistics)
Port forwarding configuration (create, delete, list)
DPI statistics (site-wide, top apps, per-client)
Redis caching with automatic invalidation
Webhook support for real-time events

Phase 6: Zone-Based Firewall (12 working tools)

Zone management (create, update, delete, list, assign networks) - 7 tools ✅ WORKING
Zone-to-zone policies via Firewall Policies v2 API - 5 tools ✅ WORKING (PR #13)
Legacy zone matrix endpoints - 5 tools ❌ ENDPOINTS DO NOT EXIST (use v2 API instead)
Application blocking per zone (DPI-based blocking) - 2 tools ❌ ENDPOINTS DO NOT EXIST
Zone statistics and monitoring - 1 tool ❌ ENDPOINT DOES NOT EXIST
Type-safe Pydantic models for ZBF and Firewall Policies
Comprehensive unit tests (84% coverage)
Endpoint verification on U7 Express and UDM Pro (v10.0.156)

Phase 7: Traffic Flow Monitoring (15 tools) ✅ COMPLETE

Real-time traffic flow monitoring and analysis
Flow filtering by IP, protocol, application, time range
Connection state tracking (active, closed, timed-out)
Client traffic aggregation with top applications/destinations
Bandwidth rate calculations for streaming flows
Security quick-response capabilities (block suspicious IPs)
Type-safe Pydantic models for traffic flows
Comprehensive unit tests (86.62% coverage)
Advanced analytics and reporting capabilities

ZBF Implementation Notes (Verified 2025-11-18):

✅ Zone CRUD operations work (local gateway API only)
✅ Zone-to-zone policies work via Firewall Policies v2 API (local gateway API only)
❌ Legacy zone matrix endpoints NOT available via API (use v2 API instead)
❌ Application blocking per zone NOT available via API
❌ Zone statistics NOT available via API
See ZBF_STATUS.md for complete details and examples

Phase 1: QoS Enhancements (11 tools) ✅

QoS profile management (CRUD operations)
Reference profiles and ProAV templates
Traffic routing with time-based schedules
Application-based QoS configuration
Coverage: 82.43% (46 tests passing)

Phase 2: Backup & Restore (8 tools) ✅

Manual and automated backup creation
Backup listing, download, and verification
Backup restore functionality
Automated scheduling with cron expressions
Cloud synchronization tracking
Coverage: 86.32% (10 tests passing)

Phase 3: Multi-Site Aggregation (4 tools) ✅

Cross-site device and client analytics
Site health monitoring with scoring
Side-by-side site comparison
Consolidated reporting across locations
Coverage: 92.95% (10 tests passing)

Phase 4: ACL & Traffic Filtering (7 tools) ✅

Layer 3/4 access control list management
Traffic matching lists (IP, MAC, domain, port)
Firewall policy automation
Rule ordering and priority
Coverage: 89.30-93.84%

Phase 5: Site Management Enhancements (9 tools) ✅

Multi-site provisioning and configuration
Site-to-site VPN setup
Device migration between sites
Advanced site settings management
Configuration export for backup
Coverage: 92.95% (10 tests passing)

Phase 6: RADIUS & Guest Portal (6 tools) ✅

RADIUS profile configuration (802.1X)
RADIUS accounting server support
Guest portal customization
Hotspot billing and voucher management
Session timeout and redirect control
Coverage: 69.77% (17 tests passing)

Phase 7: Network Topology (5 tools) ✅

Complete topology graph retrieval
Multi-format export (JSON, GraphML, DOT)
Device interconnection mapping
Port-level connection tracking
Network depth analysis
Coverage: 95.83% (29 tests passing)

Quality Achievements:

990 tests passing (78.18% coverage)
18/18 CI/CD checks passing
Zero security vulnerabilities
30+ AI assistant example prompts
Comprehensive documentation (VERIFICATION_REPORT.md, API.md)

Total: 74 MCP tools + Comprehensive documentation and verification

Version 0.3.0 (Future - Planned)

VPN Management (site_vpn.py - 0% coverage currently)
WAN Management (wans.py - 0% coverage currently)
Enhanced ZBF Matrix (zbf_matrix.py - improve 65% coverage)
Integration tests for caching and webhooks
Performance benchmarks and optimization
Additional DPI analytics (historical trends)
Bulk device/client operations
Advanced traffic flow analytics

Version 1.0.0 (Future)

Complete UniFi API coverage (remaining endpoints)
Advanced analytics dashboard
VPN configuration management
Alert and notification management
Bulk operations for devices
Traffic shaping and QoS management

Acknowledgments

This project is inspired by and builds upon:

sirkirby/unifi-network-mcp - Reference implementation
MakeWithData UniFi MCP Guide - Tutorial and guide
Anthropic MCP - Model Context Protocol specification
FastMCP - MCP server framework

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: See API.md and other docs in this repository

Links

Repository: https://github.com/enuno/unifi-mcp-server
Releases: https://github.com/enuno/unifi-mcp-server/releases
Docker Registry: https://ghcr.io/enuno/unifi-mcp-server
npm Package: https://www.npmjs.com/package/unifi-mcp-server
MCP Registry: Search for io.github.enuno/unifi-mcp-server at https://registry.modelcontextprotocol.io
Documentation: API.md | VERIFICATION_REPORT.md
UniFi Official: https://www.ui.com/

🌟 Star History

If you find this project useful, please consider starring it on GitHub to help others discover it!

Made with ❤️ for the UniFi and AI communities

Name		Name	Last commit message	Last commit date
Latest commit History 279 Commits
.claude		.claude
.cursor/rules		.cursor/rules
.github		.github
docs		docs
scripts		scripts
src		src
tests		tests
.aiignore		.aiignore
.clinerules		.clinerules
.cursorrules		.cursorrules
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.docker.example		.env.docker.example
.env.example		.env.example
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
.yamllint.yaml		.yamllint.yaml
AGENTS.md		AGENTS.md
API.md		API.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_SCANNING_REPORT.md		CODE_SCANNING_REPORT.md
CONTRIBUTING.md		CONTRIBUTING.md
CURSOR_RULES_MIGRATION.md		CURSOR_RULES_MIGRATION.md
DEVELOPMENT_PLAN.md		DEVELOPMENT_PLAN.md
Dockerfile		Dockerfile
GEMINI.md		GEMINI.md
IMPLEMENTATION_PLAN.md		IMPLEMENTATION_PLAN.md
LICENSE		LICENSE
MCP_TOOLBOX.md		MCP_TOOLBOX.md
MULTI_AGENT_PLAN.md		MULTI_AGENT_PLAN.md
PHASE2_COMPLETION_SUMMARY.md		PHASE2_COMPLETION_SUMMARY.md
PLAN.md		PLAN.md
README.md		README.md
README.npm.md		README.npm.md
RELEASE_COMPLETION_GUIDE.md		RELEASE_COMPLETION_GUIDE.md
SCRAPER_IMPLEMENTATION.md		SCRAPER_IMPLEMENTATION.md
SECURITY.md		SECURITY.md
SESSION_SUMMARY.md		SESSION_SUMMARY.md
TESTING_PLAN.md		TESTING_PLAN.md
TEST_COVERAGE_ROADMAP.md		TEST_COVERAGE_ROADMAP.md
TODO.md		TODO.md
VERIFICATION_REPORT.md		VERIFICATION_REPORT.md
WARP.md		WARP.md
ZBF_STATUS.md		ZBF_STATUS.md
copilot-instructions.md		copilot-instructions.md
coverage.json		coverage.json
docker-compose.yml		docker-compose.yml
index.js		index.js
mcp-registry.json		mcp-registry.json
package.json		package.json
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
server.json		server.json
tools.yaml		tools.yaml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

UniFi MCP Server

📋 Version Notice

🌐 API Mode Support

Local Gateway API (Recommended) ✅

Cloud Early Access API ⚠️

Cloud V1 API ⚠️

Features

Core Network Management

Security & Firewall (v0.2.0)

Quality of Service (v0.2.0)

Backup & Operations (v0.2.0)

Multi-Site Management (v0.2.0)

Network Topology (v0.2.0)

Advanced Features

Safety & Security

Technical Excellence

Quick Start

Prerequisites

Installation

Using PyPI (Recommended)

Using Docker (Alternative)

Build from Source (Development)

Using uv (Recommended)

Using pip

Using Docker Compose (Recommended for Production)

Using Docker (Standalone)

Build from Source

Prerequisites

Development Build

1. Clone the Repository

2. Set Up Development Environment

3. Configure Environment

4. Run Tests

5. Run the Server

Production Build

Build Python Package

Build Docker Image

Publishing

Publish to PyPI

Publish to npm (Metadata Wrapper)

Publish to MCP Registry

Release Process

Configuration

Obtaining Your API Key

Configuration File

Running the Server

Usage

With Claude Desktop

Option 1: Using PyPI Package (Recommended)

Option 2: Using uv with PyPI Package

Option 3: Using Docker

With Cursor

Option 1: Using PyPI Package (Recommended)

Option 2: Using uv with PyPI Package

Option 3: Using Docker

With Other MCP Clients

Using the Installed Command

Using uvx (Run from PyPI without installation)

Using Python Module Directly

Programmatic Usage

API Documentation

Development

Setup Development Environment

Running Tests

Code Quality

Testing with MCP Inspector

Project Structure

Contributing

Quick Contribution Guide

Automated Bug Reports

Security

Roadmap

Version 0.2.0 (Current - Complete ✅ 2026-01-25)

Version 0.3.0 (Future - Planned)

Version 1.0.0 (Future)

Acknowledgments

Packages