UniFi Gateway

io.github.pete-builds/unifi · v0.28.0

Safe-by-default UniFi MCP: Network + Protect + Access, multi-site, dry-run, audit log.

Website Source code Set it up

Connect Runs on your machine

Terminal

claude mcp add unifi -e STUB_MODE=<STUB_MODE> -e MCP_UNIFI_AUTH_TOKENS=<MCP_UNIFI_AUTH_TOKENS> -e MCP_UNIFI_READONLY=<MCP_UNIFI_READONLY> -e UNIFI_HOST=<UNIFI_HOST> -e UNIFI_API_KEY=<UNIFI_API_KEY> -e UNIFI_API_KEY_FILE=<UNIFI_API_KEY_FILE> -e UNIFI_PINNED_CERT=<UNIFI_PINNED_CERT> -e UNIFI_SITE=<UNIFI_SITE> -e UNIFI_VERIFY_SSL=<UNIFI_VERIFY_SSL> -e MCP_UNIFI_CONTROLLERS_FILE=<MCP_UNIFI_CONTROLLERS_FILE> -e MCP_UNIFI_MODULES_ENABLED=<MCP_UNIFI_MODULES_ENABLED> -e UNIFI_ACCESS_HOST=<UNIFI_ACCESS_HOST> -e UNIFI_ACCESS_API_KEY=<UNIFI_ACCESS_API_KEY> -e UNIFI_ACCESS_PORT=<UNIFI_ACCESS_PORT> -e MCP_UNIFI_AUDIT_SINK=<MCP_UNIFI_AUDIT_SINK> -e MCP_UNIFI_AUDIT_PATH=<MCP_UNIFI_AUDIT_PATH> -- docker run -i --rm ghcr.io/pete-builds/mcp-unifi:0.28.0

claude_desktop_config.json

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pete-builds/mcp-unifi:0.28.0"
      ],
      "env": {
        "STUB_MODE": "<STUB_MODE>",
        "MCP_UNIFI_AUTH_TOKENS": "<MCP_UNIFI_AUTH_TOKENS>",
        "MCP_UNIFI_READONLY": "<MCP_UNIFI_READONLY>",
        "UNIFI_HOST": "<UNIFI_HOST>",
        "UNIFI_API_KEY": "<UNIFI_API_KEY>",
        "UNIFI_API_KEY_FILE": "<UNIFI_API_KEY_FILE>",
        "UNIFI_PINNED_CERT": "<UNIFI_PINNED_CERT>",
        "UNIFI_SITE": "<UNIFI_SITE>",
        "UNIFI_VERIFY_SSL": "<UNIFI_VERIFY_SSL>",
        "MCP_UNIFI_CONTROLLERS_FILE": "<MCP_UNIFI_CONTROLLERS_FILE>",
        "MCP_UNIFI_MODULES_ENABLED": "<MCP_UNIFI_MODULES_ENABLED>",
        "UNIFI_ACCESS_HOST": "<UNIFI_ACCESS_HOST>",
        "UNIFI_ACCESS_API_KEY": "<UNIFI_ACCESS_API_KEY>",
        "UNIFI_ACCESS_PORT": "<UNIFI_ACCESS_PORT>",
        "MCP_UNIFI_AUDIT_SINK": "<MCP_UNIFI_AUDIT_SINK>",
        "MCP_UNIFI_AUDIT_PATH": "<MCP_UNIFI_AUDIT_PATH>"
      }
    }
  }
}

~/.cursor/mcp.json

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pete-builds/mcp-unifi:0.28.0"
      ],
      "env": {
        "STUB_MODE": "<STUB_MODE>",
        "MCP_UNIFI_AUTH_TOKENS": "<MCP_UNIFI_AUTH_TOKENS>",
        "MCP_UNIFI_READONLY": "<MCP_UNIFI_READONLY>",
        "UNIFI_HOST": "<UNIFI_HOST>",
        "UNIFI_API_KEY": "<UNIFI_API_KEY>",
        "UNIFI_API_KEY_FILE": "<UNIFI_API_KEY_FILE>",
        "UNIFI_PINNED_CERT": "<UNIFI_PINNED_CERT>",
        "UNIFI_SITE": "<UNIFI_SITE>",
        "UNIFI_VERIFY_SSL": "<UNIFI_VERIFY_SSL>",
        "MCP_UNIFI_CONTROLLERS_FILE": "<MCP_UNIFI_CONTROLLERS_FILE>",
        "MCP_UNIFI_MODULES_ENABLED": "<MCP_UNIFI_MODULES_ENABLED>",
        "UNIFI_ACCESS_HOST": "<UNIFI_ACCESS_HOST>",
        "UNIFI_ACCESS_API_KEY": "<UNIFI_ACCESS_API_KEY>",
        "UNIFI_ACCESS_PORT": "<UNIFI_ACCESS_PORT>",
        "MCP_UNIFI_AUDIT_SINK": "<MCP_UNIFI_AUDIT_SINK>",
        "MCP_UNIFI_AUDIT_PATH": "<MCP_UNIFI_AUDIT_PATH>"
      }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "unifi": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/pete-builds/mcp-unifi:0.28.0"
      ],
      "env": {
        "STUB_MODE": "<STUB_MODE>",
        "MCP_UNIFI_AUTH_TOKENS": "<MCP_UNIFI_AUTH_TOKENS>",
        "MCP_UNIFI_READONLY": "<MCP_UNIFI_READONLY>",
        "UNIFI_HOST": "<UNIFI_HOST>",
        "UNIFI_API_KEY": "<UNIFI_API_KEY>",
        "UNIFI_API_KEY_FILE": "<UNIFI_API_KEY_FILE>",
        "UNIFI_PINNED_CERT": "<UNIFI_PINNED_CERT>",
        "UNIFI_SITE": "<UNIFI_SITE>",
        "UNIFI_VERIFY_SSL": "<UNIFI_VERIFY_SSL>",
        "MCP_UNIFI_CONTROLLERS_FILE": "<MCP_UNIFI_CONTROLLERS_FILE>",
        "MCP_UNIFI_MODULES_ENABLED": "<MCP_UNIFI_MODULES_ENABLED>",
        "UNIFI_ACCESS_HOST": "<UNIFI_ACCESS_HOST>",
        "UNIFI_ACCESS_API_KEY": "<UNIFI_ACCESS_API_KEY>",
        "UNIFI_ACCESS_PORT": "<UNIFI_ACCESS_PORT>",
        "MCP_UNIFI_AUDIT_SINK": "<MCP_UNIFI_AUDIT_SINK>",
        "MCP_UNIFI_AUDIT_PATH": "<MCP_UNIFI_AUDIT_PATH>"
      }
    }
  }
}

Replace the values in angle brackets with your own. Keys stay on your machine; we never see them.

Tools

This server runs locally, so its tools are listed by your MCP client once it starts.

Environment variables

Name	Description
`STUB_MODE` Optional	When true, the server returns realistic mock data and requires no UniFi hardware. Defaults to true. Set to false to manage a real gateway, which then needs UNIFI_HOST plus UNIFI_API_KEY (or UNIFI_API_KEY_FILE), or MCP_UNIFI_CONTROLLERS_FILE. In either mode the HTTP transport will not start without…
`MCP_UNIFI_AUTH_TOKENS` Required, secret	Bearer tokens that HTTP clients must present. Required: the streamable-http transport exits at startup with 'HTTP transport requires MCP_UNIFI_AUTH_TOKENS' when it is empty. Comma-separated; each entry is a bare token (named client-N automatically) or a 'name:token' pair. Generate one with `openssl…
`MCP_UNIFI_READONLY` Optional	When true, every tool that changes state is hidden from tools/list and refused on tools/call; read tools are unaffected. Defense in depth on top of a read-only UniFi API key. Defaults to false.
`UNIFI_HOST` Optional	IP address or hostname of the UniFi OS gateway (UCG-Fiber, UDM Pro, etc). Required when STUB_MODE=false and MCP_UNIFI_CONTROLLERS_FILE is unset.
`UNIFI_API_KEY` Optional, secret	Local API key generated under Settings -> Control Plane -> Integrations on the gateway. Required when STUB_MODE=false and MCP_UNIFI_CONTROLLERS_FILE is unset, unless UNIFI_API_KEY_FILE is used instead.
`UNIFI_API_KEY_FILE` Optional	Path to a file inside the container that holds the local API key, for a Docker or Kubernetes secret mount. Wins over UNIFI_API_KEY when both are set. A controller configured this way verifies the gateway's TLS certificate unless UNIFI_VERIFY_SSL is set to false.
`UNIFI_PINNED_CERT` Optional	Path to a file inside the container that holds the gateway's own certificate in PEM, recorded with mcp-unifi-pin-cert. When set, that certificate is the only one the server accepts from the gateway, and a mismatch fails every request. Do not set UNIFI_VERIFY_SSL to false alongside it: the server re…
`UNIFI_SITE` Optional	UniFi controller site name. Defaults to 'default'.
`UNIFI_VERIFY_SSL` Optional	Whether to verify the gateway's TLS certificate. Defaults to false because most home gateways use a self-signed cert.
`MCP_UNIFI_CONTROLLERS_FILE` Optional	Path to a YAML file describing multiple named controllers for multi-site management. When set, the legacy UNIFI_HOST / UNIFI_API_KEY env vars are ignored. Each entry needs name, host, api_key, and optionally port, site, verify_ssl.
`MCP_UNIFI_MODULES_ENABLED` Optional	Comma-separated list of modules to load. Known values: 'network', 'protect', 'access'. Defaults to 'network'. Set to 'network,protect,access' to enable Protect and Access tools alongside Network. Access currently ships read-only; door unlocks and credential issuance require session-token auth and a…
`UNIFI_ACCESS_HOST` Optional	UniFi Access hub IP or hostname. Required when the access module is enabled and STUB_MODE=false. Often the same host as UNIFI_HOST.
`UNIFI_ACCESS_API_KEY` Optional, secret	UniFi Access API key. Separate from the Network API key; generated on the Access controller's developer settings. Required when the access module is enabled and STUB_MODE=false.
`UNIFI_ACCESS_PORT` Optional	HTTPS port for the Access hub. Defaults to 12445 (the direct Access app port).
`MCP_UNIFI_AUDIT_SINK` Optional	Audit log sink. One of 'file' (default), 'stdout', or 'syslog'. Every tool call is recorded to a JSONL stream with secrets scrubbed.
`MCP_UNIFI_AUDIT_PATH` Optional	Path for the audit log file when MCP_UNIFI_AUDIT_SINK=file. Defaults to audit.jsonl in the process CWD.

Details

Package	`ghcr.io/pete-builds/mcp-unifi:0.28.0` (OCI, streamable-http)
First published	11 Nov 2026
Last updated	11 Nov 2026
Registry name	`io.github.pete-builds/unifi`

More cloud and devops servers See all

Live status

Local install

Installed and run on your own machine, so there is no public endpoint to check.

Pair it with live search

Agents that use UniFi Gateway often also need current facts. NestDaddy MCP gives your AI today's internet: web search, real-time breaking news and full page reading in one connector.

See NestDaddy MCP

For maintainers

[![NestDaddy MCP](https://nestdaddy.com/mcp/servers/io-github-pete-builds-unifi/badge.svg)](https://nestdaddy.com/mcp/servers/io-github-pete-builds-unifi)

Add the badge to your README. It turns green while your server passes our daily check. Listing details come from the official MCP registry; update them there.

Listing data from the official MCP registry. Status and tools from NestDaddy's daily check. Browse all MCP servers.