by sirkirby
MCP server implementation for the UniFi network application
# Add to your Claude Code skills
git clone https://github.com/sirkirby/unifi-network-mcp![License][license-shield] ![Project Maintenance][maintenance-shield] [![GitHub Activity][commits-shield]][commits]
[![GitHub Release][release-shield]][releases] [![issues][issues-shield]][issues-link] [![test-badge]][test-workflow] [![validate-badge]][validate-workflow] [![validate-docker-badge]][validate-docker-workflow]
A self-hosted Model Context Protocol (MCP) server that turns your UniFi Network Controller into a rich set of interactive tools. Every capability is exposed via standard MCP tools prefixed with unifi_, so any LLM or agent that speaks MCP (e.g. Claude Desktop, mcp-cli, LangChain, etc.) can query, analyze and – when explicitly authorized – modify your network. These tools must have local access to your UniFi Network Controller, by either running locally or in the cloud connected via a secure reverse proxy. Please consider the security implications of running these tools in the cloud as they contain sensitive information and access to your network.
No comments yet. Be the first to share your thoughts!
confirm=true so nothing can change your network by accident.UNIFI_AUTO_CONFIRM=true to skip confirmation prompts (ideal for n8n, Make, Zapier).unifi-network-mcp.# 1. Retrieve the latest image (published from CI)
docker pull ghcr.io/sirkirby/unifi-network-mcp:latest
# 2. Run – supply UniFi credentials via env-vars or a mounted .env file
# Ensure all UNIFI_* variables are set as needed (see Runtime Configuration table)
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
# Optional: Set controller type (auto-detected if omitted)
# -e UNIFI_CONTROLLER_TYPE=auto \
# Install UV (modern pip/venv manager) if you don't already have it
curl -fsSL https://astral.sh/uv/install.sh | bash
# 1. Clone & create a virtual-env
git clone https://github.com/sirkirby/unifi-network-mcp.git
cd unifi-network-mcp
uv venv
source .venv/bin/activate
# 2. Install in editable mode (develop-install)
uv pip install --no-deps -e .
# 3. Provide credentials (either export vars or create .env)
# The server will auto-detect your controller type (UniFi OS vs standard)
# Use UNIFI_CONTROLLER_TYPE to manually override if needed
cp .env.example .env # then edit values
# 4. Launch
unifi-network-mcp
(when published)
uv pip install unifi-network-mcp # or: pip install unifi-network-mcp
The unifi-network-mcp entry-point will be added to your $PATH.
No internet access is required, everything runs locally. It's recommend you have an M-Series Mac or Windows/Linux with a very modern GPU (Nvidia RTX 4000 series or better)
Install LM Studio and edit the mcp.json file chat prompt --> tool icon --> edit mcp.json to add the unifi-network-mcp server tools, allowing you to prompt using a locally run LLM of your choice. Configure just as you would for Claude desktop. I recommend loading a tool capable model like OpenAI's gp-oss, and prompt it to use the UniFi tools.
Example prompt: using the unifi tools, list my most active clients on the network and include the type of traffic and total bandwidth used.
Use Ollama with ollmcp, allowing you to use a locally run LLM capable of tool calling via your favorite terminal.
The UniFi Network MCP server supports code-execution mode, enabling agents to write code that interacts with tools programmatically. This approach reduces token usage by up to 98% compared to traditional tool calls, as agents can filter and transform data in code before presenting results.
Code execution mode consists of three key components:
This implementation follows the patterns described in Anthropic's Code Execution with MCP article.
The server now supports lazy tool registration to dramatically reduce LLM context usage.
🎯 DEFAULT: Lazy Mode (lazy) ⭐⭐⭐ Active in v0.2.0!
Eager Mode (eager):
UNIFI_TOOL_REGISTRATION_MODE=eagerMeta-Only Mode (meta_only):
unifi_tool_index call for discoveryUNIFI_TOOL_REGISTRATION_MODE=meta_onlyUpgrading from v0.1.x?
If you're upgrading and want to restore the previous behavior (all tools registered immediately), add this to your config:
{
"mcpServers": {
"unifi": {
"command": "uv",
"args": ["--directory", "/path/to/unifi-network-mcp", "run", "python", "-m", "src.main"],
"env": {
"UNIFI_HOST": "192.168.1.1",
"UNIFI_USERNAME": "admin",
"UNIFI_PASSWORD": "password",
"UNIFI_TOOL_REGISTRATION_MODE": "eager"
}
}
}
}
Default behavior (lazy mode - recommended):
{
"mcpServers": {
"unifi": {
"command": "uv",
"args": ["--directory", "/path/to/unifi-network-mcp", "run", "python", "-m", "src.main"],
"env": {
"UNIFI_HOST": "192.168.1.1",
"UNIFI_USERNAME": "admin",
"UNIFI_PASSWORD": "password"
// UNIFI_TOOL_REGISTRATION_MODE defaults to "lazy" - no need to set!
}
}
}
}
Result: Claude starts with minimal context, tools load transparently when called - 96% token savings with zero UX compromise!
The server exposes a special unifi_tool_index tool that returns a complete list of all registered tools with their schemas:
{
"name": "unifi_tool_index",
"arguments": {}
}
Response:
{
"tools": [
{
"name": "unifi_list_clients",
"schema": {
"name": "unifi_list_clients",
"description": "List all network clients",
"input_schema": {
"type": "object",
"properties": {
"filter": {"type": "string"},
"limit": {"type": "integer"}
}
}
}
},
...
]
}
Use Cases:
The server provides two execution modes for discovered tools:
Single Tool Execution (synchronous):
{
"name": "unifi_execute",
"arguments": {
"tool": "unifi_list_clients",
"arguments": {}
}
}
Batch Execution (parallel, async):
For bulk operations or long-running tasks, use batch mode:
{
"name": "unifi_batch",
"arguments": {
"operations": [
{"tool": "unifi_get_client_details", "arguments": {"mac": "aa:bb:cc:dd:ee:ff"}},
{"tool": "unifi_get_client_details", "arguments": {"mac": "11:22:33:44:55:66"}}
]
}
}
Response:
{
"jobs": [
{"index": 0, "tool": "unifi_get_client_details", "jobId": "af33b233cbdc860c"},
{"index": 1, "tool": "unifi_get_client_details", "jobId": "bf44c344dcde971d"}
],
"message": "Started 2 operation(s). Use unifi_batch_status to check progress."
}
Check batch status:
{
"name": "unifi_b