# go-unifi-mcp

A Go MCP server that lets an AI assistant reach your UniFi Network Controller: sites, devices, clients, networks, port forwarding, DNS and firewall rules.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6
- Author: claytono
- License: MPL-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/claytono/go-unifi-mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/go-unifi-mcp

## What it does

The server wraps the go-unifi library and builds its tools from the controller's own API definitions. Tool coverage therefore tracks the UniFi Controller version that go-unifi pins. The author wrote it after failing to find an MCP server handling both v1 and v2 firewall rules plus IPv6.

Lazy mode is the default. Three meta-tools get registered — `tool_index` to search the catalog, `execute` to run one tool by name, and `batch` to run several in parallel — and they expose 252 controller operations. Switch to `eager` and all 252 tools register directly, which costs roughly 55K tokens of context; that setting suits debugging or non-LLM clients.

You need controller access before anything works. Either create an API key under Settings > Control Plane > Integrations and set `UNIFI_HOST` with `UNIFI_API_KEY`, or use a local admin account with `UNIFI_HOST`, `UNIFI_USERNAME` and `UNIFI_PASSWORD`. Writes follow a read-modify-write flow: the server fetches the current object, merges your fields, then submits the whole thing. Leave `UNIFI_HOST` unset and the server has nothing to talk to.

## Requirements
- Needs: Docker

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add go-unifi-mcp -- docker run -i --rm ghcr.io/claytono/go-unifi-mcp:v0.3.1
```

### Codex

**Platform CLI**
```bash
codex mcp add go-unifi-mcp -- docker run -i --rm ghcr.io/claytono/go-unifi-mcp:v0.3.1
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "go-unifi-mcp": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "ghcr.io/claytono/go-unifi-mcp:v0.3.1"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "go-unifi-mcp": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "ghcr.io/claytono/go-unifi-mcp:v0.3.1"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add go-unifi-mcp docker run -i --rm ghcr.io/claytono/go-unifi-mcp:v0.3.1
```

## When to use it
- list clients and devices on a UniFi network
- create a v2 or IPv6 firewall rule
- set up port forwarding through the agent
- inspect DNS records on the controller
- run several UniFi operations in one batch

## Example prompts
- List every device in the `default` site with its status
- Add a v2 firewall rule allowing traffic from VLAN 20 to VLAN 30
- Forward port 8443 to the client `nas`

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23643
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12109

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md