unifi

This UniFi MCP Server exposes the UniFi Network Controller API through the MCP framework, enabling AI agents and automation tools to interact with UniFi network infrastructure in a standardized way. The server supports multiple API modes, with Local Gateway API offering full functionality against a locally reachable UniFi gateway. You can manage devices, networks, clients, WiFi networks, and firewall rules, and you can perform actions like blocking or reconnecting clients, creating networks and VLANs, and configuring QoS or port settings. For dashboards or agents that only need high-level insights, you can use the Cloud EA or Cloud V1 modes, which provide aggregated site information without per-device access. Start the server with environment variables to select the API type and target gateway, then use the MCP client tooling to issue commands against the UniFi controller.

Prerequisites:

• Python 3.10+ installed on your system
• Access to install Python packages (pip)
• A UniFi Network Controller accessible from the host running the MCP server (for Local API) or valid cloud API credentials for cloud modes

Install the MCP package from PyPI and install dependencies:

# Optionally create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

# Install the UniFi MCP server package
pip install unifi-mcp-server

Run the MCP server (example with Local API targeting a local gateway):

export UNIFI_API_TYPE=local
export UNIFI_LOCAL_HOST=192.168.2.1
python -m unifi_mcp_server

If you prefer a cloud API, set UNIFI_API_TYPE to cloud-ea or cloud-v1 and provide any required credentials or tokens as documented by the package.

Notes and tips:

• Local API requires network reachability to the UniFi gateway (e.g., 192.168.x.x). Ensure firewall rules allow management traffic if needed.
• You can switch API modes by changing UNIFI_API_TYPE. Cloud modes expose aggregate statistics and do not allow per-device configuration.
• The MCP server exposes a comprehensive set of tools for devices, networks, QoS, backups, site management, and topology. Review the project's changelog (CHANGELOG.md) for release-specific capabilities and known issues.
• If you encounter ImportError or agnost-related startup issues, ensure you are using a Python version compatible with the package and that environment isolation (virtualenv) is active. For debugging, run with verbose logging if supported by the package.
• Consider pinning to a stable version of unifi-mcp-server to avoid breaking changes in newer releases.