Unifi Mcp Server

UniFi MCP Server

[](https://github.com/enuno/unifi-mcp-server/actions/workflows/ci.yml) [](https://github.com/enuno/unifi-mcp-server/actions/workflows/security.yml) [](https://codecov.io/github/enuno/unifi-mcp-server) [](https://pypi.org/project/unifi-mcp-server/) [](https://www.python.org/downloads/) [](LICENSE) [](https://deepwiki.com/enuno/unifi-mcp-server)

A Model Context Protocol (MCP) server that exposes the UniFi Network Controller API, enabling AI agents and applications to interact with UniFi network infrastructure in a standardized way.

📋 Version Notice

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

Installation:

pip install unifi-mcp-server

What's New in v0.2.5:

• 🚀 SSE/HTTP Transport Mode - Direct HTTP connectivity for MCP gateway integration with long-lived persistent bidirectional communication channels. Enable with UNIFI_TRANSPORT_MODE=sse and UNIFI_HTTP_PORT=8000.
• 🔧 API Compatibility Fixes - 7 critical UniFi Network 9.x fixes including firewall policy zone resolution, WLAN band parameter handling, and response parsing
• ☁️ Cloud EA API Hardening - Enhanced Site Manager endpoint resilience with graceful fallbacks and improved error handling
• 🔐 Security Updates - Dependency bumps: fastmcp → latest, MCP framework → 1.26.0+, cryptography → 46.0.5+, httpx → 0.28.1+
• 🧪 1,236 Tests Passing - Maintained high coverage across Python 3.10–3.13

See: [RELEASENOTES0.2.5.md](RELEASENOTES0.2.5.md) for complete changelog.

Current Development Posture

• Current repo codebase: ~215 async tool functions across 40+ modules
• Phases 0–2 are complete
• Phase 3 (Protect API integration) is the active implementation target
• Phase 4 adds testing, polish, minor gaps, runbooks, skills, and developer workflow hardening
• Phase 5 adds multi-controller orchestration, dry-run, RBAC, audit logging, metrics, A2A, webhooks, Access API work, and tool exposure modes for context reduction
• Canonical roadmap: 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](CHANGELOG.md) for complete release notes and [VERIFICATIONREPORT.md](docs/archive/VERIFICATIONREPORT.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=

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) 🌐

Network-accessible HTTP server — Best for MCP gateways and consolidating multiple MCPs.

• ✅ Network access: Connect from any MCP client over HTTP
• ✅ MCP gateway compatible: Works with MCP gateways that consolidate servers
• ✅ Real-time streaming: Long-lived connections for continuous communication
• ⚙️ Configuration: MCP_SERVER_TRANSPORT=sse + MCP_SERVER_PORT=3000

HTTP 🌐

Standard HTTP transport — Alternative network mode.

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

Streamable HTTP 🌐

Modern HTTP transport — Latest MCP transport standard.

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

💡 Recommendation: Use STDIO for local AI clients (Claude Desktop, Cursor). Use SSE when running behind an MCP gateway to consolidate multiple MCP servers into a single URL.

🧭 Tool Exposure Modes (Planned)

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

Planned modes

• network — network, switching, WiFi, DHCP, DNS, traffic, and client tools
• protect — cameras, NVR, events, talkback, and Protect workflows
• 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 mode 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 mode selection is explicit and repeatable

Running in SSE Mode

# Set transport to SSE
export MCP_SERVER_TRANSPORT=sse
export MCP_SERVER_PORT=3000

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

Docker Compose for SSE 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: sse
      MCP_SERVER_PORT: 3000
    ports:
      - "3000:3000"

Connecting via MCP Gateway

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

{
  "mcpServers": {
    "unifi": {
      "url": "http://your-server-ip:3000/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

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

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
docke

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [enuno](https://github.com/enuno)
- **Source:** [enuno/unifi-mcp-server](https://github.com/enuno/unifi-mcp-server)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.