UniFi Read-Only

Clone the repository. The Docker backend lives in docker/ and ships a custom-catalog.yaml alongside the Dockerfile.

$ git clone https://github.com/rosarion97/unifi-readonly-mcp-server-public.git
$ cd unifi-readonly-mcp-server-public/docker

The image tag must match the image: field in custom-catalog.yaml (unifi-readonly-mcp:latest).

$ docker build -t unifi-readonly-mcp:latest .

Three values are required: UNIFI_HOST, UNIFI_API_KEY, and UNIFI_SITE_ID. Optional: UNIFI_PORT (default 443), UNIFI_SITE_NAME (default default), UNIFI_VERIFY_TLS (default false), and the Classic-API credentials.

Find your UNIFI_SITE_ID by calling unifi_int_list_sites once with a placeholder, then copy the UUID.

$ docker mcp secret set UNIFI_API_KEY
$ docker mcp secret set UNIFI_SITE_ID
# Optional, only if you want the unifi_classic_* tools:
$ docker mcp secret set UNIFI_CLASSIC_USERNAME
$ docker mcp secret set UNIFI_CLASSIC_PASSWORD
$ docker mcp secret ls   # values are masked

With Option A, continue through Steps 4–7 below.

$ cp .env.example .env
$ chmod 600 .env   # UNIFI_HOST, UNIFI_API_KEY, UNIFI_SITE_ID required; Classic creds optional

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/docker/.env",
        "unifi-readonly-mcp:latest"
      ]
    }
  }
}

Steps 4–6 are the Option A (secret store) path. Used Option B? Skip to Step 7. After copying the catalog, open it and fill in the UNIFI_HOST, UNIFI_PORT, UNIFI_SITE_NAME, and UNIFI_VERIFY_TLS values on the unifi-readonly entry.

$ mkdir -p ~/.docker/mcp/catalogs
$ cp custom-catalog.yaml ~/.docker/mcp/catalogs/custom.yaml

Add the entry under the single top-level registry: key in ~/.docker/mcp/registry.yaml. Don't overwrite the file if it already exists.

registry:
  unifi-readonly:
    catalog: custom
    enabled: true

Add the gateway block to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). The gateway spawns the UniFi image on demand, reads your catalog and registry, and resolves your UNIFI_* secrets at request time. Replace <your-username> with your macOS username (run whoami to check):

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/Users/<your-username>/.docker/mcp:/mcp",
        "-v", "/Users/<your-username>/Library/Caches/docker-secrets-engine/engine.sock:/root/.cache/docker-secrets-engine/engine.sock",
        "docker/mcp-gateway:latest",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--registry=/mcp/registry.yaml",
        "--transport=stdio"
      ]
    }
  }
}

All three bind-mounts are required: the Docker socket lets the gateway spawn the server container; ~/.docker/mcp is where it reads your catalog and registry; the docker-secrets-engine socket is the resolver Docker Desktop exposes for the secret store, without it your UNIFI_* URLs resolve to empty strings and the server never starts. On Linux Docker Desktop the path is ~/.docker/desktop/secrets-engine/engine.sock; find it with find ~ -name engine.sock.

Then quit and reopen the client. claude_desktop_config.json never contains UNIFI_API_KEY, the gateway resolves it from Docker's secret store at request time. As a shortcut, docker mcp client connect claude-desktop (or MCP Toolkit → Clients in Docker Desktop) writes a similar block automatically; the explicit JSON above survives Docker Desktop updates that may rewrite the auto-managed entry.

$ docker mcp server list   # unifi-readonly → enabled
$ docker mcp tools list

Or run the image directly, it starts and waits silently on stdin (correct for an MCP stdio server). Press Ctrl+C to exit; a missing required value fails fast on stderr.

$ docker run --rm -i --env-file .env unifi-readonly-mcp:latest

Clone the repository. The Podman backend lives in podman/.

$ git clone https://github.com/rosarion97/unifi-readonly-mcp-server-public.git
$ cd unifi-readonly-mcp-server-public

On macOS / Windows, start a Podman machine first (podman machine init && podman machine start); Linux runs natively.

$ podman build -t unifi-readonly-mcp:latest podman/

Set them in podman/.env; the file is gitignored and chmod 600'd. Three required values, plus optional Classic-API credentials and tuning knobs.

$ cp podman/.env.example podman/.env
$ chmod 600 podman/.env   # UNIFI_HOST / UNIFI_API_KEY / UNIFI_SITE_ID required

If the UniFi console uses the stock self-signed certificate, leave UNIFI_VERIFY_TLS=false. For production, install a real cert and flip it to true.

Point Claude Desktop at the container with the absolute path to podman/.env:

{
  "mcpServers": {
    "unifi": {
      "command": "podman",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/podman/.env",
        "unifi-readonly-mcp:latest"
      ]
    }
  }
}

Claude Code takes the same invocation:

$ claude mcp add -s user unifi -- \
    podman run --rm -i \
    --env-file /absolute/path/to/podman/.env \
    unifi-readonly-mcp:latest

-i is required, MCP stdio needs stdin attached, and every --env-file path must be absolute.

Run the image manually, it starts and waits silently on stdin. Press Ctrl+C to exit; a missing required value fails fast on stderr.

$ podman run --rm -i --env-file podman/.env unifi-readonly-mcp:latest