UniFi网络管理MCP服务器

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.

Each release also includes checksums.txt with SHA-256 hashes of every binary. Download it into the same directory and verify before running:

# Linux
sha256sum --check --ignore-missing checksums.txt
# macOS
shasum -a 256 --check --ignore-missing checksums.txt

Windows users can compare the output of Get-FileHash unifi-mcp_windows_amd64.exe (PowerShell) against the matching line.

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%.

Confirm the installed version:

unifi-mcp --version

macOS users: if Gatekeeper blocks the downloaded binary, clear the quarantine flag with xattr -d com.apple.quarantine /usr/local/bin/unifi-mcp.

Install with Go

Requires Go 1.27.3+. Installs unifi-mcp into $(go env GOPATH)/bin:

go install github.com/gordcurrie/unifi-mcp/cmd/unifi-mcp@latest

Build from source

Requires Go 1.27.3+. 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:

The server needs UNIFI_SITE_ID before it will start. To find it, set UNIFI_BASE_URL and UNIFI_API_KEY in .env, load it, then query the API directly (-k skips verification of the console's self-signed certificate):

set -a && source .env && set +a
curl -sk -H "X-API-Key: $UNIFI_API_KEY" "$UNIFI_BASE_URL/integration/v1/sites"

Single-site setups have one entry; use its id.

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.

Cross-origin browser requests (mismatched Origin or Sec-Fetch-Site: cross-site) are rejected with 403; non-browser MCP clients are unaffected.

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

Claude Code configuration

claude mcp add unifi --scope user \
  -e UNIFI_BASE_URL=https://192.168.1.1/proxy/network \
  -e UNIFI_API_KEY=your-api-key \
  -e UNIFI_SITE_ID=your-site-uuid \
  -- /path/to/unifi-mcp

If your console uses its default self-signed certificate, add -e UNIFI_INSECURE=true. This disables TLS certificate and hostname verification, so only use it on a trusted network.

Run /mcp inside Claude Code to confirm the server is connected. Install the agent skills too, so Claude knows when and how to use the tools.

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"
      }
    }
  }
}

Agent skills

The skills/ directory contains Agent Skills (SKILL.md format) that teach an agent how to use these tools well:

Install them for all your projects in Claude Code:

git clone https://github.com/gordcurrie/unifi-mcp
mkdir -p ~/.claude/skills
cp -R unifi-mcp/skills/* ~/.claude/skills/

Other agents that support Agent Skills (GitHub Copilot, Cursor, Codex CLI, Gemini CLI, …) read the same folders; copy them to that agent's skills directory. Inside this repo they are already available to Claude Code and Copilot via .claude/skills and .github/skills, which link to skills/.

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