DOCSEARCHbyAlgolia
Submit Docs

UniFi MCP Server

repository·main·Indexed 41 days ago

https://github.com/enuno/unifi-mcp-server

A Model Context Protocol (MCP) server that provides tools to interact with UniFi Network Controllers, Protect, Access, and enterprise orchestration. It supports multiple API modes including Local Gateway, Cloud Early Access, and Cloud V1, with transport options for STDIO, Streamable HTTP, HTTP, and SSE. Version 0.2.0 allows for tool exposure profiles to manage context bloat and a read-only mode for enhanced safety.

Tokens
92.9K
Snippets
212
Records
426
Agent score
51%

What's inside UniFi MCP Server

  1. Overview of UniFi MCP Server

    main

    The UniFi MCP Server is a Model Context Protocol (MCP) server that exposes UniFi Network Controller functionality to AI applications (like Claude) and other software. It acts as a bridge, translating MCP tool calls and resource requests into UniFi API commands.

    Key Capabilities:

    • Device Management: List, configure, and monitor UniFi devices.
    • Network Configuration: Manage networks, VLANs, and subnets.
    • Client Information: Query connected clients and their status.
    • Firewall Rules: Create and manage firewall rules.
    • Site Management: Work with multiple UniFi sites.
    • Real-time Monitoring: Access device and network statistics.

  2. Overview of UniFi MCP Server Capabilities

    main
    The UniFi MCP Server provides an interface to the official UniFi Network Controller, Protect, and Access APIs, designed for automation by AI agents and integrations. It supports full CRUD operations for managing network infrastructure including Devices, VLANs, ACLs, Firewall Zones, WANs, DPI categories, and Hotspot Vouchers. The server uses the official /integration/v1 API structure and provides structured error reporting and advanced filtering.

  3. Understand the UniFi MCP Server project structure

    main

    The project is organized into several key directories that define its functionality as an MCP (Model Context Protocol) server:

    • bin/unifi-cli: Shell wrapper for CLI invocation.
    • skills/: Categorized Markdown files designed for AI agents to understand specific UniFi domains (e.g., unifi-network.md, unifi-devices.md, unifi-security.md, unifi-system.md).
    • src/main.py: The primary MCP server entry point, registering over 215 tools.
    • src/tools/: Contains the logic for specific MCP tools, categorized by domain (e.g., clients.py, devices.py, firewall.py, wifi.py).
    • src/api/: The core UniFi API client implementation, which includes rate limiting.
    • src/models/: Pydantic data models used for type-safe data handling (e.g., zbf.py for Zone-Based Firewall).
    • src/cache.py: Redis-based caching implementation.
    • src/memory.py: Storage for Supermemory operator notes and context.
    • docs/: Contains additional documentation, including AI coding guidelines.

  4. Project technology stack overview

    main

    The UniFi MCP Server is built using the following core technologies:

    • Python (>= 3.10): Primary programming language.
    • FastMCP: Core library for building the MCP server.
    • uv: Python package and virtual environment management.
    • httpx/requests: For performing HTTP requests to the UniFi Network API.
    • Docker: For containerization and deployment.

  5. Understand the UniFi MCP Server development roadmap

    main

    The ROADMAP.md file outlines the architectural evolution of the UniFi MCP Server across several phases. It is synchronized with DEVELOPMENT_PLAN.md and provides a high-level view of planned features, deliverables, and exit criteria for each development stage.

    Current and Future Phases

    • Phase 3: Protect API integration: Focuses on delivering native Protect coverage (cameras, devices, NVR, views, and events) on top of existing Network and Site Manager foundations.
    • Phase 4: Testing, polish, and DX: Focuses on hardening the server, adding features like Dynamic DNS CRUD and Tagged MAC management, and improving developer experience with Makefile, docker-compose.yml, and skills/ domain knowledge packs.
    • Phase 5: Enterprise scale: Focuses on multi-site orchestration, safety controls (dry-run mode), RBAC via API key scopes, observability (Prometheus), and tool exposure profiles.
    • Phase 5+: Focuses on Access expansion and other product domains.

    Version Roadmap

    VersionScopeNotes
    v0.2.5Current stable releaseBaseline release artifact
    v0.3.0Phases 0–2 completionDocs sync, Network refs, connector foundation
    v0.4.0Phase 3Protect API integration
    v0.5.0Phase 4Testing, polish, minor gaps, developer experience
    v1.0.0Phase 5Enterprise scale and operational excellence
    v1.1.0+Post-Phase 5Access expansion and later product domains

  6. Review the UniFi MCP Server roadmap and feature status

    main

    The project is organized into development phases. As of version 0.2.0, the following capabilities are available:

    Completed Features (v0.2.0)

    • Read-Only Operations: Device, Client, Network, and Site management (list, details, stats).
    • Mutating Operations: Firewall rule management, Network configuration, Device control (restart, upgrade), and Client management (block, unblock).
    • Enterprise/Operational Features: WiFi/SSID management, Port forwarding, DPI statistics, Redis caching, and Webhook support.
    • Zone-Based Firewall (ZBF): Zone CRUD and Zone-to-zone policies via the Firewall Policies v2 API (Note: Legacy zone matrix endpoints are NOT available; use v2 API).
    • Traffic Flow Monitoring: Real-time analysis, flow filtering, and connection state tracking.
    • QoS & Backup: QoS profile management, automated backups, and multi-site aggregation.
    • ACL & Traffic Filtering: Layer 3/4 ACL management and rule ordering.
    • RADIUS & Guest Portal: RADIUS profile configuration and Guest portal customization.
    • Network Topology: Complete topology graph retrieval with JSON/GraphML/DOT export.

    Planned Features (v0.3.0+)

    • VPN Management (site_vpn.py)
    • WAN Management (wans.py)
    • Enhanced ZBF Matrix
    • Bulk device/client operations
    • Advanced traffic flow analytics

  7. Understand the current capabilities and roadmap of UniFi MCP Server

    main

    The UniFi MCP Server currently provides coverage for Network, switching, firewall, QoS, topology, backup, and Site Manager foundations.

    Important Limitation: Traffic-flow historical streaming is currently constrained by API caps and is documented as unsupported.

    Future development is focused on expanding to Protect and Access APIs, implementing multi-controller orchestration, and adding safety/governance controls (like dry-run modes and audit logs).

  8. Channel Planning Rules and Scoring Heuristics

    main

    The planner uses a deterministic greedy global optimization approach. It evaluates assignments against the complete internal AP graph, re-scoring all edges after every proposed assignment to prevent local optimizations from creating global co-channel clusters.

    Scoring Logic

    Conflicts are weighted by RSSI using the following classes:

    • signal >= -55: weight 4.0
    • -65 <= signal < -55: weight 3.0
    • -75 <= signal < -65: weight 2.0
    • -85 <= signal < -75: weight 1.0

    Penalty Calculation:

    • 2.4 GHz: Same channel = rssi_weight(signal); Adjacent channel = 0.5 * rssi_weight(signal).
    • 5 GHz: Penalty is based on the overlap of occupied channel ranges (e.g., an 80 MHz AP creates more pressure than a 20 MHz AP).

  9. Safety Requirements for Mutating Operations

    main

    To prevent accidental network disruptions, all mutating (write) operations in the UniFi MCP Server follow these safety patterns:

    • Explicit Confirmation: All modifications enforce a confirm=true parameter.
    • Dry Run Support: Many tools support a dry_run=true flag to simulate changes without applying them.
    • Audit Logging: All mutations are logged with request and response data for auditability.

  10. Configure RADIUS and Authentication

    main

    Manage network access control and user authentication:

    • RADIUS Profiles: Configure RADIUS servers (e.g., FreeRADIUS) for 802.1X authentication using create_radius_profile.
    • RADIUS Accounts: Provision user credentials using create_radius_account.
    • Guest Portal: Customize the captive portal experience, including session timeouts and redirect URLs, using configure_guest_portal.
    • Hotspot Packages: Create paid WiFi access packages using create_hotspot_package. Note: The controller prices packages by the hour; bandwidth and data quotas are not supported via this API.
    • Audit Profiles: List active RADIUS profiles and check accounting status using list_radius_profiles.

  11. Understand MCP Tool Categories

    main

    The UniFi MCP Server provides tools categorized by their impact on the controller:

    • Read-only Tools: Used for querying network information without making changes.
    • Mutating Tools: Used for operations that modify settings. These include safety mechanisms such as requiring confirm=True and supporting a dry_run mode to preview changes before they are applied.

  12. Manage Backups and Disaster Recovery

    main

    Perform and automate system backups:

    • Manual Backup: Trigger a system backup using trigger_backup with backup_type="system" and a specified retention_days.
    • List Backups: View recent backups and their sizes using list_backups.
    • Download Backups: Retrieve backups to a local path using download_backup (supports checksum verification).
    • Automated Scheduling: Set up recurring backups (e.g., daily at 2 AM) using configure_backup_schedule with cron expressions.
    • Status Checks: Verify backup completion and cloud synchronization using get_backup_status.
    Prompt: "Create a full system backup of my UniFi controller right now and keep it for 90 days."
Tool call: `trigger_backup(backup_type="system", retention_days=90)`