mcp-unifi

An MCP server for self-hosted UniFi gateway management. Forty-one tools covering devices, networks/VLANs, WiFi SSIDs (full CRUD), firewall rules (full CRUD), switch port profiles (full CRUD), per-client commands (block / unblock / reconnect / quarantine), per-port state (PoE + enable + profile assignment), static DHCP leases, port forwarding (full CRUD), site health, WAN status, events, alarms, speed tests, DPI top talkers, plus four composite tools with automatic rollback on partial failure: create_iot_network, provision_homelab_service, create_guest_network, and the read-only audit_open_ports.

Built on FastMCP with two transports: stdio for per-session subprocess installs (Claude Desktop, uvx mcp-unifi) and streamable-http for the long-running container. Talks to a UCG-Fiber, UDM Pro, or any other UniFi OS gateway via the local API key. No Site Manager / cloud account required.

Every tool returns JSON. Errors come back as a structured {"error": "...", "stub_mode": bool} object so the MCP loop never crashes on a gateway hiccup.

Client compatibility

Why

Most UniFi automation today means clicking through the controller UI, writing brittle one-off scripts, or pulling in a heavyweight community SDK. mcp-unifi gives any MCP-aware client (Claude Code, Claude Desktop, custom agents) a small, focused, well-typed surface area for the operations you actually do every week: spin up an IoT VLAN, drop a firewall rule, audit your SSIDs, list adopted devices.

The composite create_iot_network tool turns a 15-step UI workflow into a single tool call.

Quick start

Two install paths. Pick the one that matches how you run Claude.

Option A: stdio (Claude Desktop, single user)

No Docker required. Install via uv directly from the GitHub repo and let Claude Desktop spawn the server per session:

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/pete-builds/mcp-unifi",
        "mcp-unifi"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "STUB_MODE": "true"
      }
    }
  }
}

Drop that into claude_desktop_config.json, restart Claude Desktop, and ask "list my UniFi devices" — you'll get two stubbed devices back. Set STUB_MODE=false plus UNIFI_HOST / UNIFI_API_KEY when you're ready to point it at a real gateway.

To pin a specific release, append @v0.4.0 (or any tag) to the git URL: git+https://github.com/pete-builds/mcp-unifi@v0.4.0.

Option B: Streamable HTTP (Docker, multi-client / homelab)

Pull the published image and run it as a long-running service:

docker run --rm \
  -p 3714:3714 \
  -e STUB_MODE=true \
  ghcr.io/pete-builds/mcp-unifi:0.4.0

The server starts in stub mode by default, which returns realistic mock data and requires no UniFi hardware. Register it with Claude Code:

claude mcp add unifi --transport http --scope user --url http://localhost:3714/mcp

To talk to a real gateway, pass the credentials and flip stub mode off:

docker run --rm \
  -p 3714:3714 \
  -e STUB_MODE=false \
  -e UNIFI_HOST=192.168.1.1 \
  -e UNIFI_API_KEY=<your-local-api-key> \
  ghcr.io/pete-builds/mcp-unifi:0.4.0

Generate the API key under Settings → Control Plane → Integrations on the gateway.

Tool reference

Every tool returns a JSON string. Errors are returned as a structured {"error": "...", "stub_mode": bool} object so Claude can render the failure without crashing the MCP loop.

Stub mode vs real mode

Switching modes is a config change, not a code change. The same eleven tools, the same response shapes.

Configuration

All configuration is read from environment variables (and a .env file when present). Config is validated by Pydantic at startup; invalid values fail fast with a helpful message.

A complete example lives in .env.example.

MCP client setup

Claude Code

claude mcp add unifi --transport http --scope user --url http://<host>:3714/mcp

Claude Desktop (stdio, recommended)

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/pete-builds/mcp-unifi",
        "mcp-unifi"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "STUB_MODE": "true"
      }
    }
  }
}

Add gateway env vars (STUB_MODE=false, UNIFI_HOST, UNIFI_API_KEY) when you're ready to leave stub mode. Note that claude_desktop_config.json is plaintext on your machine — Docker / .env mode 600 is more appropriate if your gateway sits behind sensitive credentials you don't want stored in user config.

Claude Desktop (Streamable HTTP, against a remote container)

{
  "mcpServers": {
    "unifi": {
      "transport": "streamable-http",
      "url": "http://<host>:3714/mcp"
    }
  }
}

Gemini CLI

Gemini CLI supports MCP servers over Streamable HTTP. The simplest path is the built-in subcommand, which writes the right keys to settings.json for you:

gemini mcp add unifi http://<host>:3714/mcp -t http -s user
gemini mcp list

You should see:

Configured MCP servers:

✓ unifi: http://<host>:3714/mcp (http) - Connected

If you prefer to hand-edit, drop this into ~/.gemini/settings.json (user scope) or <project>/.gemini/settings.json (project scope). The canonical Gemini CLI MCP docs use httpUrl for Streamable HTTP servers:

{
  "mcpServers": {
    "unifi": {
      "httpUrl": "http://<host>:3714/mcp",
      "timeout": 30000
    }
  }
}

The gemini mcp add subcommand currently writes a slightly different shape ("url" plus "type": "http"); both forms are accepted by recent Gemini CLI builds. Stick with whichever matches how you populated the file. Then run gemini interactively and use /mcp to inspect the connection or list available tools.

Verified against: Gemini CLI 0.36.0 on macOS. The MCP handshake (capabilities, tool/prompt/resource discovery, context refresh) completed against mcp-unifi 0.3.0 running in stub mode. Live tool execution from inside Gemini additionally requires a valid Gemini API key or OAuth login configured in the CLI; this is unrelated to the MCP wiring.

Generic config

Streamable HTTP at http://<host>:3714/mcp. Any MCP client that supports the Streamable HTTP transport (spec 2025-03-26+) can connect.

Architecture

+---------------------+         Streamable HTTP         +---------------------+
|  MCP Client         |  -------------------------->    |  mcp-unifi          |
|  (Claude Code, etc) |  <--------------------------    |  (FastMCP server)   |
+---------------------+                                 +----------+----------+
                                                                   |
                                                                   |  HTTPS + X-API-Key
                                                                   v
                                                        +----------+----------+
                                                        |  UniFi OS Gateway   |
                                                        |  /proxy/network/... |
                                                        +---------------------+

The server is a thin async proxy: it translates MCP tool calls into UniFi controller REST calls, shapes the responses, and returns JSON. It does not store state, does not call out to any cloud, and does not authenticate incoming MCP connections (run it on a trusted LAN).

Security notes

• The UNIFI_API_KEY lives only in the container's environment. It is never logged, never echoed back in MCP responses, and never written to disk by this server.
• WLAN passphrases are scrubbed ([REDACTED]) on the way out of every tool response, even in stub mode.
• The container runs as UID 1000, no shell, no home directory, with a read-only root filesystem (/tmp is tmpfs) and no-new-privileges.
• The base image is pinned by digest. Python deps are installed with pip --require-hashes from a hash-locked requirements.lock.
• The published image is multi-arch (amd64/arm64) with build provenance attestation and SBOM via docker/build-push-action.
• The MCP server itself is not authenticated. Place it behind a trusted-LAN boundary, a reverse proxy with auth, or a Tailscale ACL.

For vulnerability reports, see SECURITY.md.

Development

Requires Python 3.13+ and Docker.

# Clone + install dev deps
git clone https://github.com/pete-builds/mcp-unifi.git
cd mcp-unifi
python -m venv .venv && source .venv/bin/activate
pip install --require-hashes -r requirements-dev.lock
pip install -e . --no-deps

# Run the test suite (224 tests, ~90% coverage)
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check (mypy strict)
mypy src/mcp_unifi

# Run the server locally in stub mode
python -m mcp_unifi.server

# Or build the image yourself instead of pulling from GHCR
cp docker-compose.example.yml docker-compose.yml
docker compose up --build

Tests

======================= 224 passed in 9s =======================

Name                              Stmts  Miss  Branch  BrPart  Cover
---------------------------------------------------------------------
src/mcp_unifi/__init__.py             2     0       0       0   100%
src/mcp_unifi/clients/__init__.py     3     0       0       0   100%
src/mcp_unifi/clients/stubs.py      234     2      64       8    97%
src/mcp_unifi/clients/unifi.py      147     5      14       0    96%
src/mcp_unifi/config.py              38     1       8       0    98%
src/mcp_unifi/healthcheck.py         18     1       0       0    94%
src/mcp_unifi/logging_setup.py       33     1      12       2    93%
src/mcp_unifi/models.py               6     0       0       0   100%
src/mcp_unifi/server.py             761   107     242      18    87%
---------------------------------------------------------------------
TOTAL                              1242   117     340      28    90%

CI gates on 80% coverage minimum, ruff lint, ruff format, mypy strict, and a Trivy fs+image scan that fails on any HIGH or CRITICAL finding.

Updating dependencies

The requirements.lock and requirements-dev.lock files are hash-pinned. Edit requirements.in (or requirements-dev.in), then regenerate:

uv pip compile requirements.in --output-file requirements.lock --generate-hashes --python-version 3.13
uv pip compile requirements-dev.in --output-file requirements-dev.lock --generate-hashes --python-version 3.13

Dependabot opens weekly PRs for requirements.in-level updates and the Docker base image digest.

Acknowledgments

UniFi controller endpoint paths were cross-referenced against the sirkirby/unifi-mcp project. That repo was used as research material for the API surface; no code was copied. The implementation here is an independent FastMCP + httpx build that follows the proven Forge pattern.

License

MIT.

Contributing

Issues and pull requests welcome. Before opening a PR:

1. Make sure ruff check, ruff format --check, and mypy src/mcp_unifi are clean.
2. Add or update tests, keep coverage at 80% or above.
3. Run pytest locally and confirm the suite passes.
4. Update CHANGELOG.md under an [Unreleased] heading.