This MCP server exposes a rich suite of UniFi Network Controller tools as MCP capabilities prefixed with unifi_. You can query the server to inspect devices, clients, firewall rules, QoS settings, port-forwards, VPN configurations, WLANs, and more—without needing direct access to the UniFi UI. If your environment requires mutating actions (like changing port-forwards or firewall rules), the server enforces confirmation prompts by default to prevent accidental changes; you can enable automatic confirmations via UNIFI_AUTO_CONFIRM in your environment. Tools are designed to be discoverable by MCP clients, so you can call them individually or programmatically through code execution mode, enabling you to filter and transform results before presenting them to users or agents. The server supports both local LLMs and Claude-style interfaces, and can operate in lazy or eager tool registration modes depending on your performance and context constraints.

Prerequisites:

• Python 3.13+ and pipx/uv installed on your system
• Access to a UniFi Network Controller with credentials
• Optional: Docker if you prefer containerized deployment

Install from source (recommended for development):

1. Clone the repository: git clone https://github.com/sirkirby/unifi-network-mcp.git cd unifi-network-mcp

2. Create and activate a Python virtual environment (recommended): python -m venv .venv source .venv/bin/activate

3. Install in editable mode (development): uv pip install --no-deps -e .

4. Copy the example environment and configure credentials: cp .env.example .env

   Edit .env to set UNIFI_HOST, UNIFI_USERNAME, UNIFI_PASSWORD, UNIFI_PORT, etc.

5. Run the server using the recommended UV-based command (example): uv run python -m src.main

If you prefer Docker:

1. Build or pull the latest image: docker pull ghcr.io/sirkirby/unifi-network-mcp:latest

2. Run with environment variables for your UniFi controller: docker run -i --rm
   -e UNIFI_HOST=YOUR_CONTROLLER_HOST
   -e UNIFI_USERNAME=YOUR_USERNAME
   -e UNIFI_PASSWORD=YOUR_PASSWORD
   -e UNIFI_PORT=443
   -e UNIFI_SITE=default
   -e UNIFI_VERIFY_SSL=false
   ghcr.io/sirkirby/unifi-network-mcp:latest

Tips and common considerations:

• Security: Expose tools to trusted agents only. Mutating tools may alter your network; default prompts require confirmation unless UNIFI_AUTO_CONFIRM is set.
• Environment variables: Ensure UNIFI_HOST, UNIFI_USERNAME, UNIFI_PASSWORD, and UNIFI_PORT reflect your controller. UNIFI_VERIFY_SSL may need to be false for self-signed certs in some environments.
• Tool registration modes: lazy mode loads tools on first use and reduces context, eager mode loads all tools at startup; meta_only registers only meta-tools and requires discovery for full tool index. Set UNIFI_TOOL_REGISTRATION_MODE accordingly.
• If running in a production environment behind a reverse proxy, ensure the MCP HTTP endpoint (if enabled) is secured and not exposed publicly.
• When upgrading from older v0.1.x configurations, consult the code-execution guide to preserve your directory path and startup commands.