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>