Unifi MCP Server

UniFi MCP Server

A Model Context Protocol (MCP) server that exposes the UniFi Network Controller API today and is evolving into a production-grade multi-domain platform for Protect, Access, and enterprise-scale orchestration.

See SPEC.md for the architecture target and DEVELOPMENT_PLAN.md for the phase roadmap.

Operator quick start

Objective

Give operators a fast, safe reading order for understanding what the server does today, what it is becoming, and which docs govern rollout decisions.

Prerequisites

• You know which UniFi API mode the deployment uses: local, cloud-ea, or cloud-v1.
• You know whether the runtime is stdio, HTTP, SSE, or streamable HTTP.
• You have read the phase target in SPEC.md and the current work item in DEVELOPMENT_PLAN.md.

Procedure

1. Confirm the current stable release and current phase focus.
2. Read SPEC.md for architecture intent and DEVELOPMENT_PLAN.md for sequencing.
3. Use API.md and docs/UNIFI_API.md for implementation surface details.
4. Use the phase runbooks in NETWORK_PLAYBOOK.md, HARBOR_SETUP.md, MULTI_CONTROLLER.md, METRICS.md, WEBHOOK_SETUP.md, and A2A.md when operating or extending phase 5 systems.
5. For release work, consult RELEASE_CHECKLIST.md and docs/RELEASE_PROCESS.md before tagging or publishing.

Verification

• The chosen API mode matches the runtime configuration.
• The current phase and the documented roadmap agree.
• The operator can point to the correct runbook before making a change.

Rollback

• If the selected runbook does not match the deployed capability, stop and reconcile docs before changing production state.

Common failure modes

• README claims outrun the codebase.
• Operators follow phase language without checking the specific runbook.
• Release or rollout decisions are made from the README alone instead of the canonical docs.

📋 Version Notice

Current Stable Release: 0.2.5 (May 1, 2026) 🎉

Installation:

pip install unifi-mcp-server

Roadmap focus:

• Phase 3: native Protect API integration (camera/NVR/device/view/event read tools and resources now wired; PTZ and media streams still in progress)
• Phase 4: testing, polish, minor gaps, runbooks, skills, and developer workflow hardening
• Phase 5: multi-controller orchestration, dry-run, RBAC, audit logging, metrics, A2A, webhooks, Access API work, and tool exposure profiles

See: RELEASE_NOTES_0.2.5.md for complete changelog.

Current Development Posture

• Current repo codebase: ~220 async tool functions across 40+ modules
• Phases 0–2 are complete
• Phase 3 (Protect API integration) is the active implementation target
• The architectural target is documented in SPEC.md
• The canonical roadmap is DEVELOPMENT_PLAN.md

Previous Release - v0.2.4 (2026-02-19):

• 🚨 Critical Startup Fix (issue #42) - ImportError: cannot import 'config' from 'agnost' prevented startup. Fixed by moving agnost imports inside the conditional block.
• 📌 Dependency Pin - Excluded broken agnost==0.1.13 from 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.

🔌 Transport Modes

The UniFi MCP Server supports multiple transport modes for different deployment scenarios:

STDIO (Default) ✅

Local subprocess communication — Best for Claude Desktop, Cursor, and local AI clients.

• ✅ Default mode: No configuration needed
• ✅ Zero network overhead: Direct stdin/stdout communication
• ✅ No port required: Runs as a subprocess of the MCP client
• ⚙️ Configuration: MCP_SERVER_TRANSPORT=stdio (default)

SSE (Server-Sent Events) 🌐 ⚠️ Deprecated

Network-accessible HTTP server — legacy transport, kept for backward compatibility.

• ⚠️ Known issue: client proxies such as mcp-remote can send the first tool call before the SSE initialize handshake finishes, which the MCP SDK rejects with Received request before initialization was complete (see #96). This is a timing issue in the SSE transport itself (upstream in the mcp SDK / client proxy, not this server's tool logic), so it cannot be fixed from this codebase.
• ✅ Network access: Connect from any MCP client over HTTP
• ✅ MCP gateway compatible: Works with MCP gateways that consolidate servers
• ⚙️ Configuration: MCP_SERVER_TRANSPORT=sse + MCP_SERVER_PORT=3000
• 👉 Prefer Streamable HTTP below for any new network-accessible deployment.

HTTP 🌐

Standard HTTP transport — Alternative network mode.

• ⚙️ Configuration: MCP_SERVER_TRANSPORT=http + MCP_SERVER_PORT=3000

Streamable HTTP 🌐 ✅ Recommended for network access

Modern HTTP transport — the current MCP transport standard, and the successor to SSE.

• ✅ Network access: Connect from any MCP client over HTTP
• ✅ MCP gateway compatible: Works with MCP gateways that consolidate servers
• ✅ No SSE handshake race: session initialization is part of the same request/response cycle, avoiding the class of timing issue SSE has with proxies like mcp-remote
• ⚙️ Configuration: MCP_SERVER_TRANSPORT=streamable_http + MCP_SERVER_PORT=3000

💡 Recommendation: Use STDIO for local AI clients (Claude Desktop, Cursor). Use Streamable HTTP when running behind an MCP gateway or for any other network-accessible deployment — prefer it over SSE, which is kept only for backward compatibility.

🧭 Tool Exposure Profiles

To reduce context-window bloat, the server will support named exposure profiles that register only the tools relevant to a given UniFi application area.

Planned profiles

• network — network, switching, WiFi, DHCP, DNS, traffic, and client tools
• protect — cameras, NVRs, devices, views, events, talkback, and Protect workflows (read surfaces wired; PTZ/media streams still in progress)
• access — doors, readers, credentials, visitors, and access-control workflows
• talk — UniFi Talk devices, calls, lines, and telephony workflows
• drive — UniFi Drive storage, files, sharing, and drive workflows
• read-only — get_*, list_*, stat_*, and search_* tools only

Intended behavior

• Keep the full tool surface available when no profile is selected
• Expose fewer tools per session so agents do not carry unrelated UniFi modules in context
• Make the server easier to use in application-specific deployments and focused agent workflows
• Pair with UNIFI_PROFILE so profile selection is explicit and repeatable

Running in Streamable HTTP Mode (recommended for network access)

# Set transport to Streamable HTTP
export MCP_SERVER_TRANSPORT=streamable_http
export MCP_SERVER_PORT=3000

# Start the server
unifi-mcp-server
# Server listening on 0.0.0.0:3000 via streamable_http

Docker Compose for Streamable HTTP Mode

services:
  unifi-mcp:
    image: ghcr.io/enuno/unifi-mcp-server:latest
    environment:
      UNIFI_API_KEY: your-api-key
      UNIFI_API_TYPE: local
      UNIFI_LOCAL_HOST: 192.168.2.1
      MCP_SERVER_TRANSPORT: streamable_http
      MCP_SERVER_PORT: 3000
    ports:
      - "3000:3000"

Connecting via MCP Gateway

Once running in Streamable HTTP mode, configure your MCP gateway to connect:

{
  "mcpServers": {
    "unifi": {
      "url": "http://your-server-ip:3000/mcp"
    }
  }
}

Running in SSE Mode (deprecated)

SSE is kept for backward compatibility only — see the transport modes section above for why Streamable HTTP is preferred. To run it anyway:

export MCP_SERVER_TRANSPORT=sse
export MCP_SERVER_PORT=3000
unifi-mcp-server
# Server listening on 0.0.0.0:3000 via sse

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

Phase 5: Enterprise scale and operational excellence

• 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
• Operator Memory: Optional Supermemory integration for persisting operator notes/context across tool calls, scoped per site
• Roadmap-aligned controls: planned dry-run, RBAC, audit logging, metrics, and A2A discovery

Safety & Security

• Confirmation Required: All mutating operations require explicit confirm=True flag
• Dry-Run Mode: Planned change-safe preview path for all write and destructive operations
• Audit Logging: Planned append-only audit trail for mutation paths
• Tool Scoping: Planned API-key-based RBAC for least-privilege access
• 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,236 tests with high coverage, all passing across Python 3.10–3.13
• 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.5

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

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

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 ~220 async tool functions
• 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

# Supermemory (optional - operator notes/context storage, scoped per site)
# Requires: pip install supermemory
# Get your API key from https://console.supermemory.ai
# SUPERMEMORY_ENABLED=true
# SUPERMEMORY_API_KEY=your-supermemory-api-key-here

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

Using as a Claude Code Skill

The repo ships a SKILL.md and four categorized skill files in skills/ that let AI agents load UniFi context on-demand — without keeping all 215+ tool definitions in the LLM context for every conversation.

Install the skill

# Personal skill (available in all Claude Code sessions)
cp SKILL.md ~/.claude/skills/unifi.md

# Or install all four domain skills individually
cp skills/unifi-network.md   ~/.claude/skills/
cp skills/unifi-devices.md   ~/.claude/skills/
cp skills/unifi-security.md  ~/.claude/skills/
cp skills/unifi-system.md    ~/.claude/skills/

Once installed, Claude Code will automatically reference the skill when you ask about UniFi topics, without loading the full MCP server into every conversation.

Scoped MCP profiles (reduce context footprint)

You can run the MCP server with only the tools you need by setting UNIFI_PROFILE:

{
  "mcpServers": {
    "unifi-security": {
      "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",
        "UNIFI_PROFILE": "security"
      }
    }
  }
}

See docs/SKILLS.md for the full guide.

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)
• Tool Scope (reduces LLM context size):
  • UNIFI_PROFILE: Load only a subset of tools — network, devices, security, system, or minimal (default: all tools)
• MCP Server Transport:
  • MCP_SERVER_TRANSPORT: Transport mode (stdio, sse, http, streamable_http; default: stdio)
  • MCP_SERVER_HOST: Bind address (default: 0.0.0.0)
  • MCP_SERVER_PORT: Server port (default: 3000)

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

Command reference: commands.md

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 the current feature set
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:

• 1,236 tests passing across Python 3.10-3.13
• Coverage and module-level reporting are tracked in Codecov and CI
• Module-specific targets are maintained in DEVELOPMENT_PLAN.md and the test suite

Coverage focus areas:

• Models and validation layers
• Core tool paths and safety controls
• Network, security, and operations surfaces
• Utilities and helpers

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

Documentation truncated — see the full README on GitHub.