📡 UniFi Network MCP Server

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

Table of Contents

• Features
• Quick Start
  • Docker
  • Python / UV
  • Install from PyPI
• Using with Local LLMs and Agents
• Using with Claude Desktop
• Code Execution Mode
  • Overview
  • Context Optimization
  • Tool Index
  • Tool Execution
• Runtime Configuration
• Diagnostics (Advanced Logging)
• Developer Console (Local Tool Tester)
• Security Considerations
• 📚 Tool Catalog
• 📖 Documentation
• Testing
• Local Development
• Contributing: Releasing / Publishing

Features

• Full catalog of UniFi controller operations – firewall, traffic-routes, port-forwards, QoS, VPN, WLANs, stats, devices, clients and more.
• All mutating tools require confirm=true so nothing can change your network by accident.
• Workflow automation friendly – set UNIFI_AUTO_CONFIRM=true to skip confirmation prompts (ideal for n8n, Make, Zapier).
• Works over stdio (FastMCP). Optional HTTP endpoint (Streamable HTTP or legacy SSE) can be enabled via config.
• Code execution mode with tool index, async operations, and TypeScript examples.
• One-liner launch via the console-script unifi-network-mcp.
• Idiomatic Python ≥ 3.13, packaged with pyproject.toml and ready for PyPI.

Quick Start

Docker

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

Python / UV

# 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

Install from PyPI

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

Using with Local LLMs and Agents

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)

Recommended

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.

Alternative

Use Ollama with ollmcp, allowing you to use a locally run LLM capable of tool calling via your favorite terminal.

Code Execution Mode

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.

Overview

Code execution mode consists of three key components:

1. Tool Index - Machine-readable catalog of all available tools with JSON schemas
2. Async Operations - Background job execution for long-running operations
3. Reference Implementations - Example clients showing code-execution patterns

This implementation follows the patterns described in Anthropic's Code Execution with MCP article.

🚀 Context Optimization (New in v0.2.0)

The server now supports lazy tool registration to dramatically reduce LLM context usage.

🎯 DEFAULT: Lazy Mode (lazy) ⭐⭐⭐ Active in v0.2.0!

• Registers only 3 meta-tools initially
• ~200 tokens consumed (96% reduction!)
• Tools loaded automatically on first use
• Seamless UX - no manual discovery needed
• Best of both worlds!
• Active by default - no configuration needed

Eager Mode (eager):

• Registers all 86 tools immediately
• ~5,000 tokens consumed for tool schemas
• All tools visible in context from start
• Best for: Dev console, automation scripts
• How to enable: Set UNIFI_TOOL_REGISTRATION_MODE=eager

Meta-Only Mode (meta_only):

• Registers only 3 meta-tools initially
• ~200 tokens consumed (96% reduction!)
• Requires unifi_tool_index call for discovery
• Best for: Maximum control
• How to enable: Set UNIFI_TOOL_REGISTRATION_MODE=meta_only

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

Tool Index

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:

• Programmatic tool discovery
• Wrapper/SDK generation
• Dynamic client configuration
• IDE autocomplete support

Tool Execution

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