mcpserver.so LogoMCPFly
Submit
UniFi Network MCP Server logo

UniFi Network MCP Server

by sirkirby

Networking/AutomationUniFiNetwork ControllerAutomationAPI

A self-hosted Model Context Protocol (MCP) server that turns your UniFi Network Controller into a rich set of programmable tools. It exposes UniFi Network Controller capabilities via standard MCP tools, allowing LLMs or agents to query, analyze, and modify your network (with explicit confirmation).

View on GitHub

Last updated: N/A

📡 UniFi Network MCP Server

License

License

Project Maintenance

Project Maintenance

GitHub Activity

GitHub Activity

GitHub Release

GitHub Release

issues

issues
validate-badge

validate-badge
validate-docker-badge

validate-docker-badge

"Buy Me A Coffee"

"Buy Me A Coffee"

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

  • 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