mcp -unifi

This MCP server provides a bridge to manage UniFi networks via natural language by wrapping the UniFi Network API. It exposes an MCP endpoint that can be queried by AI agents (such as Goose or Claude Desktop) to retrieve information about sites and devices, or to perform actions supported by the UniFi API. The local server authenticates requests with an API key and serves a lightweight inspector UI for testing and debugging at http://localhost:5173. To use it, start the server with the provided MCP runtime (uv) and then integrate it with your AI agent or workflow, sending MCP-style requests to the running server.

Once running, you can leverage the following capabilities: discover UniFi sites, list devices, fetch device details, and query network topology or device status. Goose AI and Claude Desktop configurations are provided to connect the MCP server to those agents via the specified command and environment variables. Ensure your UNIFI_API_KEY is set in the environment so the server can authenticate to the UniFi Network API.

Prerequisites:

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

1. Clone the repository

git clone https://github.com/zcking/mcp-server-unifi
cd mcp-server-unifi

2. Set up a Python virtual environment with uv

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

3. Install dependencies (if required by uv setup in this project)

uv sync

4. Configure environment variables (example)

export UNIFI_API_KEY="your_api_key_here"

5. Run the MCP development server

uv run mcp dev main.py

6. Open the MCP Inspector to test endpoints

http://localhost:5173

Tips and observations:

• Ensure UNIFI_API_KEY is kept secret and not committed to source control.
• If the MCP Inspector fails to load, verify that the UniFi API key is valid and the UniFi Network application is reachable from the host.
• The server is designed to work with Goose AI and Claude Desktop; for Claude, update the claude_desktop_config.json with the provided mcpServers entry.
• If you modify main.py or the directory structure, restart the uv task to pick up changes.
• For troubleshooting, check the running process logs and confirm that the Inspector UI is accessible at the default port 5173.