unifi-network-mcp 0.1.3

Unifi Network MCP Server

📡 UniFi Network MCP Server

A self-hosted Model Context Protocol (MCP) server that turns your UniFi Network Controller into a rich set of programmable 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, analyse and – when explicitly confirmed – modify your network.

---

Table of Contents

• Features
• Quick Start
  • Docker
  • Python / UV
  • Install from PyPI
• Using with Claude Desktop
• Runtime Configuration
• Diagnostics (Advanced Logging)
• Developer Console (Local Tool Tester)
• 📚 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 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

Variable	Description
CONFIG_PATH	Full path to a custom config YAML file. If not set, checks CWD for config/config.yaml, then falls back to the bundled default (src/config/config.yaml).
UNIFI_HOST	IP / hostname of the controller
UNIFI_USERNAME	Local UniFi admin
UNIFI_PASSWORD	Admin password
UNIFI_PORT	HTTPS port (default 443)
UNIFI_SITE	Site name (default default)
UNIFI_VERIFY_SSL	Set to false if using self-signed certs
UNIFI_MCP_HTTP_ENABLED	Set true to enable optional HTTP SSE server (default false)

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.

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:2b:2f:cd:5b:fc

• 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

---

📚 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 GitHub Actions workflow.

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

MIT