Unifi MCP Server

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: 0.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,325 Tests Passing - 1219 unit + 106 integration tests, cloud-ea API compatibility fixes, Site Manager endpoint hardening

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 ⚠️

Site-centric access - UniFi cloud API with limited but functional read-only capabilities.

• ✅ Site Management: List sites, get site details (matches by siteId, _id, name, or meta.name)
• ✅ Site Manager API (optional): Multi-site aggregation, host inventory, cross-site statistics
  • Enable with UNIFI_SITE_MANAGER_ENABLED=true
  • Gracefully degrades when endpoints are unavailable
• ⚠️ 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 + optional UNIFI_SITE_MANAGER_ENABLED=true
• 📊 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,325 tests (1,219 unit + 106 integration) 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.4

# 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

1. Log in to UniFi Site Manager
2. Navigate to Settings → Control Plane → Integrations
3. Click Create API Key
4. Save the key immediately - it's only shown once!
5. 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

# Site Manager API (cloud-ea only, optional)
# UNIFI_SITE_MANAGER_ENABLED=true

# 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)
  • UNIFI_SITE_MANAGER_ENABLED: Enable Site Manager multi-site tools for cloud-ea (default: false)

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
├── DEVELOPMENT_PLAN.md    # Development roadmap
├── docs/archive/          # Archived planning & session docs
├── 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

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes
4. Run tests and linting: pytest && pre-commit run --all-files
5. Commit with conventional commits: feat: add new feature
6. 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 docs/archive/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 (docs/archive/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!

Documentation truncated — see the full README on GitHub.