A self-hosted Python-based MCP server that transforms UniFi Network Controller into 86+ LLM-callable tools. Enables Claude Desktop, mcp-cli and other clients to manage firewall, VPN, WLAN, devices and clients via natural language, with context optimization (Lazy/Eager modes) and safety confirmation mechanisms.
Project Overview#
UniFi Network MCP Server is a Model Context Protocol (MCP) server that acts as a bridge between UniFi Network Controller API and LLMs, enabling MCP-compatible clients like Claude Desktop, mcp-cli, and LangChain to safely query, analyze, and modify network configurations.
Core Capabilities#
Network Management#
- Complete Operations Catalog: Covers Firewall, QoS, VPN, WLAN, Port Forwards, Traffic Routing configurations
- System Monitoring: Query Stats, Events, Alarms, DPI data
- Devices & Clients: Device restart/upgrade, client listing, block/authorize guests
MCP/LLM Integration#
- Context Optimization:
- Lazy Mode (default): Registers only 3 meta-tools, ~200 tokens (96% reduction)
- Eager Mode: Registers all 86+ tools, ~5,000 tokens
- Meta-Only Mode: Register meta-tools only, manual tool index invocation
- Code Execution: JSON Schema tool index, batch parallel execution support
Security & Operations#
- Safety Confirmation: All modification operations require
confirm=trueby default, preventing LLM hallucination-induced accidents - Permission Tiers (v0.2.0): High-risk operations disabled by default (network modification/device operations), read-only and low-risk policy operations enabled
- Automation Friendly:
UNIFI_AUTO_CONFIRM=truefor n8n, Make, Zapier non-interactive scenarios
Connectivity#
- Multi-transport Protocols: stdio (FastMCP primary), optional HTTP endpoint (Streamable HTTP/SSE)
- Auto-detection: Automatically identifies UniFi OS proxy paths vs standard paths, ~300ms detection time
Architecture#
LLM Client (Claude/mcp-cli) <--(stdio/HTTP)--> UniFi Network MCP Server <--(HTTPS)--> UniFi Controller
- Core Framework: FastMCP (based on MCP protocol)
- API Adapter Layer: Handles REST API interaction, authentication, path conversion with UniFi Controller
- Tool Registration System: Dynamically loads tool definitions based on configuration mode
Deployment#
Docker (Recommended)#
docker pull ghcr.io/sirkirby/unifi-network-mcp:latest
docker run -i --rm \
-e UNIFI_HOST=192.168.1.1 \
-e UNIFI_USERNAME=admin \
-e UNIFI_PASSWORD=secret \
-e UNIFI_PORT=443 \
-e UNIFI_SITE=default \
-e UNIFI_VERIFY_SSL=false \
ghcr.io/sirkirby/unifi-network-mcp:latest
PyPI Installation#
pip install unifi-network-mcp
# or with uv
uv pip install unifi-network-mcp
Key Configuration#
| Environment Variable | Description | Default |
|---|---|---|
UNIFI_HOST | Controller IP/hostname | Required |
UNIFI_USERNAME | Local admin | Required |
UNIFI_PASSWORD | Admin password | Required |
UNIFI_SITE | Site name | default |
UNIFI_AUTO_CONFIRM | Auto-confirm changes | false |
UNIFI_TOOL_REGISTRATION_MODE | Tool loading mode | lazy |
UNIFI_MCP_HTTP_ENABLED | Enable HTTP interface | false |
Use Cases#
- Smart Home/Home Lab: Manage home network via natural language through Claude Desktop
- Ops Automation: Integrate with n8n, Make, Zapier for event-based network responses
- Network Analysis: Generate health reports using LLM analysis of DPI data and system events