unifi-mcp

An MCP server that exposes UniFi Network operations as tools, built in Go using the official go-sdk.

Tools

All list_* tools accept optional offset and limit parameters for pagination and return a Page[T] object with data, totalCount, offset, limit, and count fields. limit must be ≤ 1000 (values above 1000 are rejected with an error). Most tools also accept an optional site_id; omit it to use the default configured via UNIFI_SITE_ID.

Sites

Devices

Clients

Network

Destructive (opt-in)

These tools are not registered by default. Set UNIFI_ALLOW_DESTRUCTIVE=true to enable them.

Why are all ACL writes destructive-gated? Any ACL mutation directly controls which traffic is allowed or blocked. A misplaced BLOCK rule — or a reorder that promotes one — can cause a complete network outage. UNIFI_ALLOW_DESTRUCTIVE=true is the primary guard; confirmed: true is the per-call secondary guard.

Installation

Download a pre-built binary

Download the latest release for your platform from the Releases page.

Make it executable and place it on your PATH (substitute the filename for your platform):

chmod +x <binary-name>
mv <binary-name> /usr/local/bin/unifi-mcp

Windows users: rename unifi-mcp_windows_amd64.exe to unifi-mcp.exe and place it in a directory on your %PATH%.

Build from source

Requires Go 1.26+. You will also need a UniFi OS console (UCG-Max, UDM-Pro, etc.) with an API key generated under UniFi OS → Settings → API.

git clone https://github.com/gordcurrie/unifi-mcp
cd unifi-mcp
cp .env.example .env   # copy the example env file
$EDITOR .env           # set UNIFI_* values (see table below)
make build             # binary lands in bin/unifi-mcp

Configuration

All configuration is via environment variables:

Source your .env file before running:

set -a && source .env && set +a

Running

stdio (default — for local MCP clients)

unifi-mcp
# or, if running directly from a source build:
./bin/unifi-mcp

HTTP (streamable — for remote/shared deployments)

The HTTP transport has no built-in authentication. Use a loopback address or place it behind a reverse proxy before exposing it on a shared network.

unifi-mcp --transport http --addr 127.0.0.1:8080

VS Code Copilot configuration

Create .vscode/mcp.json in your workspace (already gitignored):

{
  "servers": {
    "unifi-mcp": {
      "type": "stdio",
      "command": "/path/to/unifi-mcp/bin/unifi-mcp",
      "env": {
        "UNIFI_BASE_URL": "https://192.168.1.1/proxy/network",
        "UNIFI_API_KEY": "your-api-key",
        "UNIFI_SITE_ID": "your-site-uuid"
      }
    }
  }
}

Then open the Copilot chat panel, switch to Agent mode, and the unifi-mcp server will appear in the available tools.

Claude Desktop configuration

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "unifi-mcp": {
      "command": "/path/to/unifi-mcp/bin/unifi-mcp",
      "env": {
        "UNIFI_BASE_URL": "https://192.168.1.1/proxy/network",
        "UNIFI_API_KEY": "your-api-key",
        "UNIFI_SITE_ID": "your-site-uuid"
      }
    }
  }
}

Restart Claude Desktop after saving the config — the UniFi tools will appear in the tool selector.

OpenCode configuration

Add the server to opencode.json in your project root (or ~/.config/opencode/opencode.json for global config):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unifi-mcp": {
      "type": "local",
      "command": ["/path/to/unifi-mcp/bin/unifi-mcp"],
      "enabled": true,
      "environment": {
        "UNIFI_BASE_URL": "https://192.168.1.1/proxy/network",
        "UNIFI_API_KEY": "your-api-key",
        "UNIFI_SITE_ID": "your-site-uuid"
      }
    }
  }
}

Development

make install-tools   # install golangci-lint, gosec, govulncheck, gofumpt
make check           # full quality gate: fix, fmt, vet, lint, sec, vulncheck, test, build
make test            # tests only (with race detector)
make build           # build only → bin/unifi-mcp
make clean           # remove bin/unifi-mcp