Unifi MCP Server

by enuno

184 stars

288 downloads

Not rated

GitHub

Other

About

An MCP server that leverages official UniFi API

Details

Author: enuno
GitHub stars: 184
Downloads: 288
Categories: Other

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

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
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.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Install via pip: pip install unifi-mcp-server. Set environment variables for API mode (e.g., UNIFI_API_TYPE=local) and transport (e.g., MCP_SERVER_TRANSPORT=stdio), then run unifi-mcp-server. For SSE mode, set MCP_SERVER_TRANSPORT=sse and expose a port.

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

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

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

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

UniFi MCP Server

Operator quick start

Objective

Prerequisites

Procedure

Verification

Rollback

Common failure modes

📋 Version Notice

Current Development Posture

🌐 API Mode Support

Local Gateway API (Recommended) ✅

Cloud Early Access API ⚠️

Cloud V1 API ⚠️

🔌 Transport Modes

STDIO (Default) ✅

SSE (Server-Sent Events) 🌐

HTTP 🌐

Streamable HTTP 🌐

🧭 Tool Exposure Profiles

Planned profiles

Intended behavior

Running in SSE Mode

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀