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

#  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

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](CONTRIBUTING.md# automated-workflows) 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!

[](https://www.star-history.com/# enuno/unifi-mcp-server&type=date&legend=top-left)

---

Made with ❤️ for the UniFi and AI communities