UniFi

You can manage and query UniFi network devices using natural language through MCP by running a local server that wraps the UniFi Network API. This makes it easy to ask questions about sites, devices, and configurations and get actionable results from AI agents like Goose and Claude Desktop, all without exposing your API credentials. This guide walks you through installation, running, and practical usage with MCP clients.

How to use

Run the local MCP server and connect it to your UniFi Network application using your UniFi API key. Start the server with your preferred MCP client (Goose or Claude Desktop). Once the server is running, you can interact with it through natural language to query UniFi sites, devices, and configurations. The MCP Inspector at http://localhost:5173 lets you test and debug your setup.

Typical usage patterns include asking for the list of sites, listing devices in a site, checking device statuses, and retrieving configuration details. If you need to change the UniFi API key, update the environment variable and restart the server so all requests are authenticated.

How to install

Prerequisites you need to prepare before installation:

• Python 3.8 or higher
• uv package manager
• UniFi Network application
• UniFi API key from UniFi console

Step 1. Create an API key for UniFi Network access. Use your UniFi console and obtain an API key from Settings » Control Plane » Integrations. Note the key for later use.

Step 2. Clone and set up the MCP UniFi server locally.

# Clone the MCP UniFi server repo
git clone https://github.com/zcking/mcp-server-unifi
cd mcp-server-unifi

# Create and activate a Python virtual environment using uv
uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

Configure and run locally

Step 3. Install dependencies and set your environment variable.

uv sync
export UNIFI_API_KEY="your_api_key_here"

Run the MCP server and test with the Inspector

Step 4. Start the MCP development server and access the inspector for testing.

uv run mcp dev main.py

AI agent integration guidance

Goose AI and Claude Desktop can connect to this MCP server to interact with UniFi data. Use the following snippets to configure each agent with the local MCP server endpoint and your API key.

Goose AI setup

1. Open Goose and go to Settings » Extensions » Add custom extension
2. Configure the extension:
   - ID: unifi
   - Name: unifi
   - Description: Get information about your UniFi network
   - Command: `/Users/username/.local/bin/uv --directory /path/to/mcp-server-unifi run main.py```
3. Environment Variables: Set UNIFI_API_KEY to your API key

Claude Desktop setup

Add a configuration entry to Claude Desktop to point to the local MCP server.

{
  "mcpServers": {
    "unifi": {
      "command": "/Users/username/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-unifi",
        "run",
        "main.py"
      ]
    }
  }
}

Notes on security and testing

• Keep your UniFi API key secret. Do not expose it in logs or shared configurations. Use environment variables and restart the server after updating keys.

• The MCP Inspector at http://localhost:5173 lets you test commands and verify that the server returns expected results before you start interacting with live agents.

Troubleshooting

If you encounter authentication issues, verify that UNIFI_API_KEY is correctly exported in your shell and that the UniFi Network application is reachable from the host running the MCP server.

If the inspector reports connectivity problems, check network access, firewall rules, and ensure the UniFi Network app is running and accessible.

Available tools

sites_query

Query UniFi sites using natural language through the MCP interface to retrieve site names, IDs, and summary details.

devices_query

Query devices within a UniFi site to list device IDs, types, statuses, and locations.