Skip to main content
This guide walks you through everything you need to get UniFi MCP Server running and connected to an AI assistant. You’ll need a UniFi account at unifi.ui.com and Python 3.10 or higher installed on your machine.
1

Get your UniFi API key

UniFi MCP Server authenticates with the UniFi API using an API key, which you generate from the UniFi Site Manager.
  1. Log in to unifi.ui.com
  2. Navigate to Settings → Control Plane → Integrations
  3. Click Create API Key
  4. Copy the key and store it somewhere secure
The API key is shown only once. If you navigate away without copying it, you’ll need to create a new one.
2

Install the server

Install UniFi MCP Server from PyPI using pip or run it directly with uvx without a permanent installation.Install with pip (recommended):
Run without installing, using uvx:
After installing with pip, the unifi-mcp-server command is available globally.
3

Set your environment variables

The server reads its configuration from environment variables. At minimum, you need UNIFI_API_KEY and UNIFI_API_TYPE.For Local Gateway mode (recommended):
Replace 192.168.2.1 with the IP address of your UniFi gateway.For Cloud v1 mode:
You can set these in your shell, in a .env file in the project directory, or directly in your MCP client configuration (shown in the next step).
Use Local Gateway mode (UNIFI_API_TYPE=local) for full access to all 77 tools, including the ability to create networks, configure firewall rules, and control devices. Cloud API modes are limited to read-only site statistics.
4

Connect to Claude Desktop

Open your Claude Desktop configuration file and add the UniFi MCP Server entry. The config file is located at:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
Using pip installation with Local Gateway:
Using uvx with Cloud v1:
After saving the file, restart Claude Desktop to load the new server.
5

Test with a sample prompt

Once Claude Desktop restarts, open a new conversation and try asking:
“List my UniFi devices”
If the server is connected correctly, Claude will use the list_devices tool and return a list of your UniFi devices with their names, models, and status.You can also try:
  • “Show me all connected clients on my network”
  • “What are the current firewall rules on site default?”
  • “Give me a summary of my UniFi sites”

​
Next steps

API modes

Understand the differences between Local Gateway, Cloud v1, and Cloud EA modes.

MCP client setup

Detailed configuration for Claude Desktop, Cursor, and other clients.