What is Unifi Network Mcp

unifi-network-mcp is a self-hosted Model Context Protocol (MCP) server designed to enhance the UniFi Network Controller with programmable tools, allowing for querying, analyzing, and modifying network configurations.

Use cases

Use cases include automating network configurations, monitoring network performance, managing firewall rules, and integrating with other applications or services that support MCP.

How to use

To use unifi-network-mcp, you can deploy it via Docker, Python, or install it from PyPI. After setting it up, you can interact with it using MCP-compatible tools like Claude Desktop or mcp-cli.

Key features

Key features include a comprehensive catalog of UniFi controller operations, requiring explicit confirmation for network modifications, support for FastMCP over stdio, and an SSE HTTP endpoint for real-time updates.

Where to use

unifi-network-mcp is suitable for network administrators, developers, and IT professionals who manage UniFi networks and seek to automate or enhance their network management capabilities.

📡 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
• 📚 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) and exposes an SSE HTTP endpoint (defaults to :3000).
• One-liner launch via the console-script mcp-server-unifi-network.
• 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
mcp-server-unifi-network

Install from PyPI

(when published)

uv pip install unifi-network-mcp  # or: pip install unifi-network-mcp

The mcp-server-unifi-network 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"
  ]
}

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

@unifi-network-mcp list tools

---

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

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.

---

📚 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

---

License

MIT