Unifi MCP Server

by enuno

184 288 downloads Not rated yet Apache-2.0
GitHub Website

About

An MCP server that leverages official UniFi API

Details

License
Apache-2.0

Explore

- Device management (list, restart, locate, upgrade)
- Network, VLAN, DHCP, and WiFi configuration
- Client management with block/unblock and analytics
- Port profile and switch port configuration
- Firewall rules and ACL management
- Multi-site aggregation and cross-site statistics
- 220+ async tool functions across 40+ modules

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Unifi MCP Server
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

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


pip install unifi-mcp-server

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/>

curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"



python -m venv .venv

source .venv/bin/activate  # On Windows: .venv\Scripts\activate


pip install -e ".[dev]"

cp .env.docker.example .env

Using uv (Recommended):


curl -LsSf https://astral.sh/uv/install.sh | sh

source .venv/bin/activate  # Linux/macOS


uv pip install -e ".[dev]"


pre-commit install

pre-commit install --hook-type commit-msg

Using pip:
bash

cp .env.example .env

uv pip install build

uv pip install twine

brew install mcp-publisher

Create a .env file in the project root:


UNIFI_LOCAL_HOST=192.168.2.1
UNIFI_LOCAL_PORT=443
UNIFI_LOCAL_VERIFY_SSL=false
bash

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

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


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.

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

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "unifi mcp server": {
            "unifi": {
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-e",
                    "UNIFI_API_KEY=$API_KEY",
                    "-e",
                    "UNIFI_API_TYPE=cloud",
                    "ghcr.io/enuno/unifi-mcp-server:latest"
                ]
            }
        }
    }
}

McpServers

{
    "unifi": {
        "command": "docker",
        "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "UNIFI_API_KEY=$API_KEY",
            "-e",
            "UNIFI_API_TYPE=cloud",
            "ghcr.io/enuno/unifi-mcp-server:latest"
        ]
    }
}

CI
Security
codecov
PyPI
Python
License
Ask DeepWiki

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

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 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, 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 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 SSE Mode

```bash

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Videos about Unifi MCP Server

Relevant YouTube tutorials, setups, and demos

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

— 88.2k 508.3k dl
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

— 88.1k 6.7k dl
Other

EverArt

EverArt MCP Server connects compatible AI clients with EverArt image generation, allowing models and agents to create and manage artwork through Model Context…

— 88.1k 3.6k dl
Other

Google Drive

Google Drive MCP Server connects compatible AI clients with Google Drive files and folders, allowing models and agents to find and read documents through Model…

— 88.1k 2.4k dl
Other