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 + MCP_AUTH_TOKEN=<token>

⚠️ Authentication is required for network transports. The MCP endpoint exposes every registered tool, including destructive ones. http, sse, and streamable_http will refuse to start unless MCP_AUTH_TOKEN is set; clients then send Authorization: Bearer <token>. The server binds to 127.0.0.1 by default — terminate TLS and authenticate at a reverse proxy before widening MCP_SERVER_HOST to 0.0.0.0.

💡 Recommendation: Use STDIO for local AI clients (Claude Desktop, Cursor). Use Streamable HTTP when running behind an authenticating MCP gateway or reverse proxy — 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
# Required — the server refuses to start a network transport without it
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)

# Start the server (binds to 127.0.0.1 by default)
unifi-mcp-server
# Server listening on 127.0.0.1:3000 via streamable_http
# Clients send: Authorization: Bearer $MCP_AUTH_TOKEN

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
      MCP_SERVER_HOST: 0.0.0.0            # container-internal; keep the published port on loopback
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}   # required — clients send Authorization: Bearer <token>
    ports:
      # Published on loopback; put an authenticating TLS proxy in front to expose it further.
      - "127.0.0.1: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 127.0.0.1:3000 via sse (MCP_AUTH_TOKEN required)

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

• Read-Only Mode: Set UNIFI_READ_ONLY=true to register only non-mutating tools — state-changing tools are then absent from the MCP tool list entirely, rather than relying on a caller-supplied confirm flag
• 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