sirkirby/unifi-network-mcp

📡 UniFi Network MCP Server

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
• Runtime Configuration
• Diagnostics (Advanced Logging)
• Developer Console (Local Tool Tester)
• Security Considerations
• 📚 Tool Catalog
• 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.
• Works over stdio (FastMCP). Optional SSE HTTP endpoint can be enabled via config.
• One-liner launch via the console-script unifi-network-mcp.
• Idiomatic Python ≥ 3.10, 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

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)
# Ensure your .env file (or exported variables) include all required UNIFI_*
# settings as detailed in the Runtime Configuration table below (e.g., UNIFI_HOST,
# UNIFI_USERNAME, UNIFI_PASSWORD, UNIFI_PORT, UNIFI_SITE, UNIFI_VERIFY_SSL).
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.

Using with Claude Desktop

Add (or update) the unifi-network-mcp block under mcpServers in your claude_desktop_config.json.

Option 1 – Claude invokes the local package

"unifi-network-mcp": {
  "command": "/path/to/your/.local/bin/uvx",
  "args": ["--quiet", "unifi-network-mcp"], // Or "unifi-network-mcp==<version>"
  "env": {
    "UNIFI_HOST": "192.168.1.1",
    "UNIFI_USERNAME": "admin",
    "UNIFI_PASSWORD": "secret",
    "UNIFI_PORT": "443",
    "UNIFI_SITE": "default",
    "UNIFI_VERIFY_SSL": "false"
  }
}

• uvx handles installing/running the package in its own environment.
• The --quiet flag is recommended if uvx outputs non-JSON messages.
• If you want to pin to a specific version, use "unifi-network-mcp==<version_number>" as the package name.
• If your script name in pyproject.toml differs from the package name, use ["--quiet", "<package-name>", "<script-name>"].

Option 2 – Claude starts a Docker container

"unifi-network-mcp": {
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-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"
  ]
}

Option 3 – Claude attaches to an existing Docker container (recommended for compose)

1. Using the container name as specified in docker-compose.yml from the repository root:

docker-compose up --build

2. Then configure Claude Desktop:

"unifi-network-mcp": {
  "command": "docker",
  "args": ["exec", "-i", "unifi-network-mcp", "unifi-network-mcp"]
}

Notes:

• Use -T only with docker compose exec (it disables TTY for clean JSON). Do not use -T with docker exec.
• Ensure the compose service is running (docker compose up -d) before attaching.

After editing the config restart Claude Desktop, then test with:

@unifi-network-mcp list tools

Optional HTTP SSE endpoint (off by default)

For environments where HTTP is acceptable (e.g., local development), you can enable the HTTP SSE server and expose it explicitly:

docker run -i --rm \
  -p 3000:3000 \
  -e UNIFI_MCP_HTTP_ENABLED=true \
  ...
  ghcr.io/sirkirby/unifi-network-mcp:latest

Security note: Leave this disabled in production or sensitive environments. The stdio transport remains the default and recommended mode.

Runtime Configuration

The server merges settings from environment variables, an optional .env file, and src/config/config.yaml (listed in order of precedence).

Essential variables

src/config/config.yaml

Defines HTTP bind host/port (0.0.0.0:3000 by default) plus granular permission flags. Examples below assume the default port.

Diagnostics (Advanced Logging)

Enable a global diagnostics mode to emit structured logs for every tool call and controller API request. Only recommended for debugging.

Configuration in src/config/config.yaml:

server:
  diagnostics:
    enabled: false            # toggle globally
    log_tool_args: true       # include tool args/kwargs (safely redacted)
    log_tool_result: true     # include tool results (redacted)
    max_payload_chars: 2000   # truncate large payloads

Environment overrides:

• UNIFI_MCP_DIAGNOSTICS (true/false)
• UNIFI_MCP_DIAG_LOG_TOOL_ARGS (true/false)
• UNIFI_MCP_DIAG_LOG_TOOL_RESULT (true/false)
• UNIFI_MCP_DIAG_MAX_PAYLOAD (integer)

Notes:

• Logs are emitted via standard Python logging under unifi-network-mcp.diagnostics.
• Set server.log_level (or UNIFI_MCP_LOG_LEVEL) to INFO/DEBUG to surface entries.
• Tool calls log timing and optional redacted args/results; API calls log method, path, timing, and redacted request/response snapshots.

Developer Console (Local Tool Tester)

A lightweight interactive console to list and invoke tools locally without LLM tool calling. It uses your normal config and the same runtime, so diagnostics apply automatically when enabled. Grab your favorite terminal to get started.

Location: devtools/dev_console.py

Run:

python devtools/dev_console.py

What it does:

• Loads config and initializes the UniFi connection.
• Auto-loads all unifi_* tools.
• Lists available tools with descriptions.
• On selection, shows a schema hint (when available) and prompts for JSON arguments.
• Executes the tool via the MCP server and prints the JSON result.

Tips:

• Combine with Diagnostics for deep visibility: set UNIFI_MCP_DIAGNOSTICS=true (or enable in src/config/config.yaml).
• For mutating tools, set {"confirm": true} in the JSON input when prompted.

Supplying arguments

You can provide tool arguments in three ways:

• Paste a JSON object (recommended for complex inputs):

  {"mac_address": "14:1b:4f:dc:5b:cf"}
  

• Type a single value when the tool has exactly one required parameter. The console maps it automatically to that key. Example for unifi_get_client_details:

  14:1b:4f:dc:5b:cf

• Press Enter to skip JSON and the console will interactively prompt for missing required fields (e.g., it will ask for mac_address).

Notes:

• For arrays or nested objects, paste valid JSON.
• The console shows a schema hint (when available). Defaults from the schema are used if you press Enter on a prompt.
• If validation fails, the console extracts required fields from the error and prompts for them.

Environment setup

Using UV (recommended):

# 1) Install UV if needed
curl -fsSL https://astral.sh/uv/install.sh | bash

# 2) Create and activate a virtual environment
uv venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows PowerShell: .venv\\Scripts\\Activate.ps1

# 3) Install project and dependencies
uv pip install -e .

# 4) (If you see "ModuleNotFoundError: mcp") install the MCP SDK explicitly
uv pip install mcp

# 5) Run the console
python devtools/dev_console.py

Using Python venv + pip:

# 1) Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows PowerShell: .venv\\Scripts\\Activate.ps1

# 2) Install project (and dependencies)
pip install -e .

# 3) (If you see "ModuleNotFoundError: mcp") install the MCP SDK explicitly
pip install mcp

# 4) Run the console
python devtools/dev_console.py

Security Considerations

These tools will give any LLM or agent configured to use them full access to your UniFi Network Controller. While this can be for very useful for analysis and configuration of your network, there is potential for abuse if not configured correctly. By default, all tools that can modify state or disrupt availability are disabled, and must be explicitly enabled in the src/config/config.yaml file. When you have a use case for a tool, like updating a firewall policy, you must explicitly enable it in the src/config/config.yaml and restart the MCP server. The tools are build directly on the UniFi Network Controller API, so they can operate with similar functionality to the UniFi web interface.

General Recommendations

• Use LM Studio or Ollama run tool capable models locally if possible. This is the recommended and safest way to use these tools.
• If you opt to use cloud based LLMs, like Claude, Gemini, and ChatGPT, for analysis. Enable read-only tools, which is the default configuration.
• Create, update, and removal tools should be used with caution and only enabled when necessary.
• Do not host outside of your network unless using a secure reverse proxy like Cloudflare Tunnel or Ngrok. Even then, an additional layer of authentication is recommended.

📚 Tool Catalog

All state-changing tools require the extra argument confirm=true.

Firewall

• unifi_list_firewall_policies
• unifi_get_firewall_policy_details
• unifi_toggle_firewall_policy
• unifi_create_firewall_policy
• unifi_update_firewall_policy
• unifi_create_simple_firewall_policy
• unifi_list_firewall_zones
• unifi_list_ip_groups

Traffic Routes

• unifi_list_traffic_routes
• unifi_get_traffic_route_details
• unifi_toggle_traffic_route
• unifi_update_traffic_route
• unifi_create_traffic_route
• unifi_create_simple_traffic_route

Port Forwarding

• unifi_list_port_forwards
• unifi_get_port_forward
• unifi_toggle_port_forward
• unifi_create_port_forward
• unifi_update_port_forward
• unifi_create_simple_port_forward

QoS / Traffic Shaping

• unifi_list_qos_rules
• unifi_get_qos_rule_details
• unifi_toggle_qos_rule_enabled
• unifi_update_qos_rule
• unifi_create_qos_rule
• unifi_create_simple_qos_rule

Networks & WLANs

• unifi_list_networks
• unifi_get_network_details
• unifi_update_network
• unifi_create_network
• unifi_list_wlans
• unifi_get_wlan_details
• unifi_update_wlan
• unifi_create_wlan

VPN

• unifi_list_vpn_clients
• unifi_get_vpn_client_details
• unifi_update_vpn_client_state
• unifi_list_vpn_servers
• unifi_get_vpn_server_details
• unifi_update_vpn_server_state

Devices

• unifi_list_devices
• unifi_get_device_details
• unifi_reboot_device
• unifi_rename_device
• unifi_adopt_device
• unifi_upgrade_device

Clients

• unifi_list_clients
• unifi_get_client_details
• unifi_list_blocked_clients
• unifi_block_client
• unifi_unblock_client
• unifi_rename_client
• unifi_force_reconnect_client
• unifi_authorize_guest
• unifi_unauthorize_guest

Statistics & Alerts

• unifi_get_network_stats
• unifi_get_client_stats
• unifi_get_device_stats
• unifi_get_top_clients
• unifi_get_dpi_stats
• unifi_get_alerts

System

• unifi_get_system_info
• unifi_get_network_health
• unifi_get_site_settings

Contributing: Releasing / Publishing

This project uses PyPI Trusted Publishing via a .

To publish a new version:

1. Bump the version in pyproject.toml.
2. Create a new GitHub Release: Draft a new release on GitHub, tagging it with the exact same version number (e.g., v0.2.0 if the version in pyproject.toml is 0.2.0).

Once published, users can install it via:

uv pip install unifi-network-mcp

Local Development

Docker:

docker compose up --build

Python:

python3 -m venv .venv
source .venv/bin/activate
pip install .

License