New advertisers: 50% off your first month with code FIRSTMONTHSee slots
sirkirby avatar

unifi-sitemanager

Read-only UniFi cloud inventory plugin that reads account-wide sites, devices, ISP metrics, and SD-WAN.

GitHub stars
1.1K
View on GitHub

What it does

  • Adds the unifi-sitemanager skill for reading cloud hosts, sites, devices, WAN metrics, and SD-WAN status
  • Adds the unifi-sitemanager-setup skill for configuring keyless startup, credential providers, and reconnecting after a key change
  • Covers one account-wide cloud inventory through Ubiquiti's Site Manager API rather than a single local console
  • Designed for users who need read-only visibility across every UniFi site in their account

Read-only UniFi Site Manager cloud inventory, ISP metrics and SD-WAN across the whole account

Add marketplace

/plugin marketplace add sirkirby/unifi-mcp

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install unifi-sitemanager@unifi-plugins

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Set up UniFi Site Manager

  1. Choose the client. Use Claude Code, Codex or OpenClaw. Other clients use the repository's native/manual server installation instructions; do not invent plugin configuration for them. Real-client acceptance of this bundle is not yet measured. Locate this installed plugin's root from the skill path.

  2. Check prerequisites. Run bash <plugin-root>/scripts/check-prereqs.sh --target <client> or & <plugin-root>/scripts/check-prereqs.ps1 -Target <client> on Windows. Install uv/uvx and the chosen client CLI when missing. The server needs Python 3.13 or newer (uv can supply it); setup needs Python 3.11 or newer and falls back to uv. Internet access to Ubiquiti's https://api.ui.com is required.

  3. Explain the scope. A Site Manager API key grants visibility across the whole UniFi account. Ask the user to create a cloud key in Site Manager and choose exactly one source below. Never ask for the value in chat. This server has no console host, username, password, port, site or TLS setting and no permission or policy options. Never reuse or migrate UNIFI_API_KEY or a console credential.

  4. Save the one credential. Accept only UNIFI_SITEMANAGER_API_KEY, UNIFI_SITEMANAGER_API_KEY_FILE or UNIFI_SITEMANAGER_API_KEY_COMMAND. Two nonempty forms are refused. Provider files must be nonempty readable absolute paths; command providers name an available executable and argv, run without a shell by the server. Setup validates references without running a command provider or reading the key file's contents.

    Claude Code's plugin options offer a sensitive masked API key field, stored in its system keychain, and file/command fields. Prefer a provider. For Codex and OpenClaw, use a provider reference with the bundled settings script:

    bash <plugin-root>/scripts/set-env.sh --target codex UNIFI_SITEMANAGER_API_KEY_FILE=/absolute/path/to/key
    
    & <plugin-root>/scripts/set-env.ps1 -Target codex UNIFI_SITEMANAGER_API_KEY_FILE=C:\private\key
    

    Choose claude or openclaw instead when appropriate. The raw key must travel only as a JSON patch on stdin (--input-json / -InputJson) from a local masked prompt or secret manager. Never place it in a command argument, shell history, output, logs, or a conversation. If a masked input mechanism is unavailable, use a provider. Claude Code setup calls claude plugin configure with values on stdin, using the existing keychain mechanism. Switching from a keychain value may require clearing it in a newer Claude Code or reinstalling; follow the helper's value-free guidance rather than saving two forms.

    Codex and OpenClaw save only the key source in the private per-user file ~/.config/unifi-mcp/sitemanager.env (Windows: %USERPROFILE%\.config\unifi-mcp\sitemanager.env). Their bundled .mcp.codex.json points there through UNIFI_SETTINGS_FILE; setup creates no MCP client entry. If a manual entry shadows the bundle, remove it with the client editor and rerun; Site Manager never migrates console settings.

  5. Reconnect. Claude Code: /reload-plugins or start a new session to load new options; use /mcp reconnect plugin:unifi-sitemanager:unifi-sitemanager only if /mcp shows the server as failed. Codex: start a new session. OpenClaw: start a new session or restart the Gateway when an open session keeps the unconfigured server. Plugin upgrades take effect from the next agent turn. Codex setup warms the pinned package without a settings file or credential; it performs no authenticated read. With no key the server starts in keyless setup mode instead of connecting. Once the user agrees to an account-wide read, discover a bounded inventory read through the main unifi-sitemanager skill. Report only status and counts, never credential values. All domain tools read; there are no writes or support-bundle tool.

From the sirkirby/unifi-mcp README

UniFi MCP

UniFi MCP — AI agents for your UniFi infrastructure

Leverage agents and agentic AI workflows to manage your UniFi deployment.

PyPI - Network PyPI - Protect PyPI - Access PyPI - Site Manager PyPI - Relay PyPI - API Server npm - Worker License: MIT Python 3.13+

Servers

ServerStatusToolsPackage
NetworkStable217unifi-network-mcp
ProtectStable68unifi-protect-mcp
AccessStable38unifi-access-mcp
Site ManagerBeta9unifi-sitemanager-mcp
InnerSpaceNot yet released9unifi-innerspace-mcp (run from source)

Network, Protect, Access and InnerSpace each connect to a console you name on your network. Site Manager is different: it reads Ubiquiti's cloud Site Manager API at https://api.ui.com with one account-wide key, and has nine read-only tools. It counts its domain tools only, without the meta-tools every server registers.

InnerSpace is not yet released. It reads the floor plans, walls and device placements of the UniFi InnerSpace application on a console, with a console login rather than an API key, and has nine read-only domain tools, counted the same way. There is no released package, image or plugin for it yet; run it from a checkout.

Plugins

Install these from the Claude Code, Codex or OpenClaw marketplace; Quick Start shows how.

PluginWhat you get
unifi-networkThe Network MCP server, its agent skills and guided setup
unifi-protectThe Protect MCP server, its agent skills and guided setup
unifi-accessThe Access MCP server, its agent skills and guided setup
unifi-sitemanagerThe Site Manager MCP server for a whole UI account, its agent skills and guided key setup
unifi-intelligenceCross-product investigations that use Network and Protect together, with every claim cited. Incident Investigation runs locally; Security Patrol and Visitor Audit need the cloud worker. It requires the Network and Protect plugins

The Agent Skills table lists every skill each plugin ships.

Choose an integration

What you are buildingUseWhy
An AI assistant or another existing MCP clientNetwork, Protect, or Access MCP serverStandard MCP discovery, tool calls, permissions, and confirmation flows
Floor plans, walls and placed devices from a console's InnerSpace applicationInnerSpace MCP server (not yet released; from source)Read-only reads through a console login session; no API key path
An account-wide view of every console, site and device on a UI accountSite Manager MCP serverRead-only inventory, WAN health and SD-WAN status from Ubiquiti's cloud with one Site Manager API key
A custom application, automation service, code-execution runtime, or MCP adapterunifi-api-serverYour code controls call sequencing, data joins, resource limits, and approval flow
Remote access for an MCP clientCloud RelayAuthenticated remote MCP routing without exposing the local servers directly

An MCP adapter can expose a small set of tools while using unifi-api-server as its backend. This keeps application-specific joins, branching, loops, and code isolation out of the general-purpose MCP servers.

Cloud Relay

ComponentStatusPackage
Relay SidecarBetaunifi-mcp-relay
Worker GatewayBetaunifi-mcp-worker (CLI)

Cloud Relay pairs the Cloudflare-hosted Worker gateway with the Relay sidecar on your LAN. The Worker provides the authenticated edge MCP endpoint, Durable Object broker, multi-location routing, token boundary, and deployment/management CLI. The Relay sidecar is a local MCP HTTP client and forwarder: it discovers configured local MCP servers over HTTP and maintains an outbound WebSocket to the Worker. Remote requests follow MCP client → Worker gateway → outbound WebSocket → Relay sidecar → local MCP servers over HTTP; the API server is not in this path. Read-only tools support annotation-based multi-location fan-out, while writes require explicit location targeting. Deploy the Worker with npm install -g unifi-mcp-worker && unifi-mcp-worker install, then see the Relay sidecar README to connect local servers.

REST + GraphQL API

ComponentStatusPackage
API ServerBetaunifi-api-server · GHCR image

unifi-api-server is an independent HTTP service for custom applications, automation, and adapters. It provides typed REST resources, read-only GraphQL queries, SSE streams, scoped API keys and administration, plus a REST action endpoint for supported controller operations. It shares unifi-core managers with the MCP servers but does not proxy or require them.

The API server also serves the nine Site Manager reads once an administrator adds one account-level cloud connection. Every API key with the read scope can then read the whole cloud account; see Site Manager cloud connection. It serves the nine InnerSpace reads for a controller that declares the innerspace product with a username and password, and never returns plan image bytes; see InnerSpace console product.

See apps/api/README.md for quick-start and deployment patterns.

What is this?

UniFi MCP is a collection of Model Context Protocol servers that let AI assistants and automation tools interact with Ubiquiti UniFi controllers. Each server targets a specific UniFi application (Network, Protect, Access) and exposes its functionality as MCP tools — queryable, composable, and safe by default.

Those three servers are local-first: they talk directly to your console, and nothing leaves your network unless you add the optional Cloud Relay. The Site Manager server is the exception. Every request it makes goes to Ubiquiti's cloud at https://api.ui.com, even when your MCP client runs it locally over stdio. The destination is fixed, and its key reads every console on the account. The Cloud Relay does not include it unless you add it to UNIFI_RELAY_SERVERS; a relay token for that location could then read the whole account. See Site Manager and the privacy policy.

The InnerSpace server, not yet released, is local-first like the console servers: it talks only to the console you name, with a console login. The Cloud Relay does not include it unless you add it to UNIFI_RELAY_SERVERS, and floor plans describe a building, so weigh that before you do.

MCP HTTP Access

MCP HTTP is unauthenticated by default and intended for trusted local clients. Set UNIFI_MCP_HTTP_AUTH_TOKEN to require a static bearer token on every HTTP request (details). HTTP is disabled by default; when enabled, packages bind to loopback. Docker Compose enables it on the container network and publishes ports 3000–3002 on host 127.0.0.1; the Site Manager service uses port 3003 and the InnerSpace service port 3005, and each starts only with its own opt-in profile (sitemanager, innerspace). Use an authenticated TLS proxy or Cloud Relay for remote access, and prevent direct access to the backend. See the transport security model and HTTP setup and migration.

SettingDefaultPurpose
UNIFI_MCP_HTTP_ENABLEDfalseOpt into HTTP transport
UNIFI_MCP_HOST127.0.0.1Bind address; Compose explicitly uses 0.0.0.0 inside containers
UNIFI_MCP_HTTP_FORCEfalseAllow HTTP outside container PID 1
UNIFI_MCP_STDIO_ENABLEDtrueSet false to serve HTTP alone from a process that is not PID 1 (an init-managed container or a service manager); needs UNIFI_MCP_HTTP_ENABLED=true and UNIFI_MCP_HTTP_FORCE=true
UNIFI_MCP_ALLOWED_HOSTSlocalhost,127.0.0.1Complete accepted Host-header list; Compose separately adds required internal hosts. List each host: the MCP SDK has no wildcard beyond a :* port suffix, so an entry with any other * (*, *.example.com) stops the server at startup instead of accepting every host
UNIFI_MCP_ENABLE_DNS_REBINDING_PROTECTIONtrueValidate Host headers to prevent DNS-rebinding requests
UNIFI_MCP_HTTP_AUTH_TOKENunsetRequire Authorization: Bearer <token> on every HTTP request; at least 32 printable ASCII characters. UNIFI_<NETWORK|PROTECT|ACCESS|SITEMANAGER|INNERSPACE>_MCP_HTTP_AUTH_TOKEN overrides it per server, and _FILE/_COMMAND spellings work. Set but empty refuses startup

MCP Discovery

UniFi MCP keeps the standard MCP path primary: capable clients discover currently registered tools with tools/list and invoke them with tools/call. The default lazy mode keeps initial context small by exposing meta-tools first, while eager mode registers all selected domain tools directly for clients that prefer a full standard tool list.

The lazy-loading meta-tools — *_tool_index, *_execute, *_batch, *_batch_status, *_batch_cancel, and lazy-only *_load_tools — support filtered discovery, indirect execution, batch orchestration, and optional direct registration. They are independent of the protocol-version response compatibility policy below. See MCP Discovery and Lazy-Loading Meta-Tools for mode-by-mode behavior.

MCP response size

For tool results that already provide structured output, adaptive response mode is the default. It classifies each request by the canonical date-based protocolVersion advertised during MCP initialization, not by the client's product name or application version. Requests advertising MCP 2025-06-18 or later receive concise text in content and the full result once in structuredContent; requests advertising an earlier revision (such as 2024-11-05 or 2025-03-26), or whose revision metadata is missing or malformed, retain the full compatibility JSON in content. Set UNIFI_MCP_CONTENT_MODE=compat to force that duplicated compatibility form, or UNIFI_MCP_CONTENT_MODE=compact to force concise text plus the full structured result even outside a negotiated request. Use compat for any client that consumes the full result only from content, regardless of its advertised revision.

The lazy-loading meta-tools remain content-only; they are not the pre-2025-06-18 protocol category described above. For structured inner results, *_execute and *_batch_status expose one normalized JSON payload in content rather than a nested transport pair; content-only execute results remain unchanged. Response modes do not convert these meta-tools to structuredContent.

UNIFI_NETWORK_MCP_CONTENT_MODE, UNIFI_PROTECT_MCP_CONTENT_MODE, UNIFI_ACCESS_MCP_CONTENT_MODE, UNIFI_SITEMANAGER_MCP_CONTENT_MODE, and UNIFI_INNERSPACE_MCP_CONTENT_MODE override the global setting for their respective servers. Independently of transport compaction, Network's unifi_get_dashboard defaults to summary=true, while unifi_list_rogue_aps defaults to a summarized page of at most 100 records; pass summary=false when the full selected data is required.

Quick Start

Install with your agent

Paste the block below into your coding agent. It points the agent at the canonical, versioned setup guide and limits what it may change:

Install UniFi MCP for me using the official instructions at:
https://github.com/sirkirby/unifi-mcp/blob/main/docs/agent-install.md

Before changing anything, identify my agent client and operating system, ask
whether I need Network, Protect, Access, or more than one, and show me the exact
commands and configuration files you plan to change. Wait for my confirmation.
Do not ask me to paste a password or API key into chat. Prefer an indirect
credential provider or the client's secure secret prompt. Keep mutation
permissions in confirm mode and explicitly deny create, update, and delete
unless I opt in. After setup, reload the client, verify the MCP connection and
tool list, and run one harmless read-only check.

The guide covers native plugins, product-scoped npx skills add installs, OpenCode's built-in MCP support, and the current manual paths for Antigravity, Cursor, and Devin Desktop. A skills install adds agent guidance; it does not by itself register the MCP server.

See the changelog for what each plugin release changed, and the plugin upgrade guide before updating an existing install.

Claude Code (recommended)

Install via the plugin marketplace — includes the MCP server, an agent skill, and guided setup:

/plugin marketplace add sirkirby/unifi-mcp
/plugin install unifi-network@unifi-plugins
/unifi-network:unifi-network-setup

Repeat for Protect or Access if needed:

/plugin install unifi-protect@unifi-plugins
/plugin install unifi-access@unifi-plugins

For an account-wide view from Ubiquiti's cloud, /plugin install unifi-sitemanager@unifi-plugins, then run its setup skill to give it a Site Manager API key as a file or command provider. It asks for no console host or login.

For the cross-product skills, /plugin install unifi-intelligence@unifi-plugins also installs the Network and Protect plugins it needs. Claude Code opens no options dialog for plugins it installs as dependencies, so run each product's setup command (/unifi-network:unifi-network-setup, /unifi-protect:unifi-protect-setup) for any not yet configured.

/plugin install of a product plugin opens its options dialog straight away; fill it in there, or close it and run the setup command. Each plugin's setup command walks you through connecting to your controller and configuring permissions, and saves the result as the plugin's Claude Code options. Auto-update is off by default for this marketplace; see the plugin upgrade guide for update steps.

Prerequisites, version boundaries and verification status for each client are in the plugin support matrix.

Codex

Register the UniFi MCP marketplace, then install the plugins from Codex's /plugins UI:

codex plugin marketplace add sirkirby/unifi-mcp

Launch codex, run /plugins, open the UniFi MCP marketplace, and install unifi-network, unifi-protect, unifi-access, or unifi-sitemanager. unifi-intelligence adds the cross-product skills; Codex does not install plugin dependencies, so install and set up unifi-network and unifi-protect before it. After installing, ask Codex to run the plugin's setup skill, for example:

Use the unifi-network-setup skill to configure this for Codex.

The setup skill saves your controller settings and credential provider references in a private file, ~/.config/unifi-mcp/<product>.env, which the plugin's own server reads, and keeps the same preview-before-confirm safety model as Claude Code. Codex installs plugin upgrades itself at the start of a session, and the server comes with them, so nothing needs rerunning. If you ran Codex setup before plugin 1.0.0, run its one-time --refresh; see the plugin upgrade guide.

UniFi account requirements

The Network, Protect and Access servers authenticate to the local UniFi controller APIs with a local admin/service account. Do not use a Ubiquiti SSO cloud account for their setup. For Network MCP today, accounts that require SSO MFA or local 2FA are not supported through configuration; use a dedicated local admin account without MFA for the service account, scoped to the permissions you are comfortable giving the MCP server.

The Site Manager server needs no console account. It uses a Site Manager API key created at unifi.ui.com under Settings > API Keys, which reads every console the UI account can see.

OpenClaw

OpenClaw can install the same UniFi plugin bundles from the marketplace and map their skills plus MCP server definitions into embedded Pi sessions:

openclaw plugins install unifi-network --marketplace https://github.com/sirkirby/unifi-mcp
openclaw gateway restart

In a terminal OpenClaw asks you to confirm the source and the plugin's capabilities. Without a terminal, for example in a script, add --force --accept-capabilities; otherwise it refuses.

Then run the matching setup skill from OpenClaw (unifi-network-setup, unifi-protect-setup, or unifi-access-setup), or run the plugin's setup script yourself. Point the password at a credential provider so the secret never appears in the command line:

bash ~/.openclaw/extensions/unifi-network/scripts/set-env.sh --target openclaw \
  UNIFI_NETWORK_HOST=192.168.1.1 \
  UNIFI_NETWORK_USERNAME=admin \
  'UNIFI_NETWORK_PASSWORD_FILE=/absolute/path/to/password-file'

Setup saves these settings in ~/.config/unifi-mcp/network.env, readable by you only, and the plugin's own server reads that file. It adds no entry to openclaw.json, so openclaw plugins update brings each new server version with nothing to rerun. An mcp.servers.unifi-network entry in openclaw.json replaces the plugin's server and pins its version; setup before plugin 1.0.0 wrote one, and set-env.sh --target openclaw --refresh converts it once (see the upgrade guide). Repeat with unifi-protect or unifi-access as needed. Install unifi-intelligence for the cross-product skills only after setting up unifi-network and unifi-protect; OpenClaw does not install plugin dependencies.

Other MCP clients

Run the servers directly:

uvx unifi-network-mcp@latest
uvx unifi-protect-mcp@latest
uvx unifi-access-mcp@latest
uvx unifi-sitemanager-mcp@latest

For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "unifi-network": {
      "command": "uvx",
      "args": ["unifi-network-mcp@latest"],
      "env": {
        // Server-specific vars take priority; credentials follow the host (see Multi-controller setups)
        "UNIFI_NETWORK_HOST": "192.168.1.1",
        "UNIFI_NETWORK_USERNAME": "admin",
        "UNIFI_NETWORK_PASSWORD": "your-password"
      }
    },
    "unifi-protect": {
      "command": "uvx",
      "args": ["unifi-protect-mcp@latest"],
      "env": {
        "UNIFI_PROTECT_HOST": "192.168.1.1",
        "UNIFI_PROTECT_USERNAME": "admin",
        "UNIFI_PROTECT_PASSWORD": "your-password"
      }
    },
    "unifi-access": {
      "command": "uvx",
      "args": ["unifi-access-mcp@latest"],
      "env": {
        "UNIFI_ACCESS_HOST": "192.168.1.1",
        "UNIFI_ACCESS_USERNAME": "admin",
        "UNIFI_ACCESS_PASSWORD": "your-password"
      }
    }
  }
}

Tip: If all servers connect to the same controller, you can use the shared UNIFI_HOST / UNIFI_USERNAME / UNIFI_PASSWORD variables instead of repeating them per server. A server given its own host that is not UNIFI_HOST needs its own username and password too; see Multi-controller setups.

Site Manager

Give the Site Manager server only its own key, in a file only you can read. It takes none of the console variables above:

{
  "mcpServers": {
    "unifi-sitemanager": {
      "command": "uvx",
      "args": ["unifi-sitemanager-mcp@latest"],
      "env": {
        "UNIFI_SITEMANAGER_API_KEY_FILE": "/Users/you/.config/unifi-mcp/sitemanager-api-key"
      }
    }
  }
}

It uses stdio by default; HTTP is opt-in on port 3003. See the Site Manager README.

InnerSpace from source

The InnerSpace server is not yet released: there is no PyPI package, container image or plugin. Run it from a checkout with uv. It reads InnerSpace through a console login, takes no API key, and never reads UNIFI_API_KEY:

git clone https://github.com/sirkirby/unifi-mcp.git
cd unifi-mcp
uv sync
export UNIFI_INNERSPACE_HOST=192.168.1.1
export UNIFI_INNERSPACE_USERNAME=innerspace-reader
export UNIFI_INNERSPACE_PASSWORD_FILE="$HOME/.config/unifi-mcp/innerspace-password"
uv run --package unifi-innerspace-mcp unifi-innerspace-mcp

It uses stdio by default; HTTP is opt-in on port 3005. See the InnerSpace README.

Usage Examples

Once connected, just ask your AI agent in natural language:

Network

"Show me all clients on the Guest VLAN with their signal strength and data usage" "Create a firewall rule that blocks IoT devices from reaching the internet between midnight and 6 AM" "Audit my firewall policies — are there any redundant or conflicting rules?" "Show me the top traffic flows from the last hour and group them by destination"

Protect

"List all cameras that detected motion in the last hour" "Show me smart detection events from the front door camera today — people and vehicles only" "Find driveway detections for white vans this week"

Access

"Who badged into the office today? Show me a timeline of all door access events" "Create a visitor pass for John Smith with access to the main entrance tomorrow 9-5"

Site Manager

"List every console on my UniFi account with its OS version and whether it is connected" "Which sites had WAN downtime or high latency in the last 24 hours?"

InnerSpace (not yet released)

"Which floor plans does my InnerSpace project have, and how many access points are placed on each?" "List the devices I have adopted but not yet placed on a floor plan"

UniFi Intelligence (the unifi-intelligence plugin)

"Switch aa:bb:cc:00:10:02 dropped off at 8:45 this morning, New York time. What happened between 8:00 and 9:00?" — cites Network events and mapped Protect camera events with their coverage "Show me everything that happened at the front entrance in the last hour" — needs the cloud worker and relay

All mutations use a preview-then-confirm flow (Site Manager has none: every one of its domain tools reads) — you see exactly what will change before anything is applied.

Configuration

Set these variables in the server's process environment (shell exports, the MCP client's env block, or Docker environment: / env_file:):

VariableRequiredDescription
UNIFI_HOSTYesController IP or hostname
UNIFI_USERNAMEYesLocal admin/service account username; do not use a Ubiquiti SSO account
UNIFI_PASSWORDYesPassword for the local account
UNIFI_API_KEYNoUniFi API key for selected capabilities, including firewall policy ordering and some Protect settings updates
CONFIG_PATHNoAbsolute path to an operator-controlled custom YAML file; otherwise uses bundled configuration
UNIFI_SETTINGS_FILENoAbsolute path (~ allowed) to a per-user settings file of UNIFI_* variables; see below
UNIFI_DEFER_CONTROLLER_INITNoNetwork only: make no controller connection at startup and connect on the first tool call instead. By default every server answers the MCP client at once and connects in the background
UNIFI_META_TOOLS_ENABLEDNoNetwork eager mode only: set false to omit indirect meta-tools; requires UNIFI_ENABLED_CATEGORIES or UNIFI_ENABLED_TOOLS

Startup configuration: The servers do not automatically load .env files or config/config.yaml from the working directory. MCP clients may launch servers inside untrusted projects, so project files must not control where credentials are sent or weaken permissions and redaction. If you previously relied on automatic loading, select a trusted env file in your launcher (for example, uv run --env-file /absolute/path/to/trusted.env --with unifi-network-mcp unifi-network-mcp) or set an absolute CONFIG_PATH for custom YAML. Docker Compose env_file: remains supported.

Per-user settings file: UNIFI_SETTINGS_FILE names a file the server reads at startup, before anything else reads configuration. The Codex plugin's setup writes ~/.config/unifi-mcp/<product>.env and points its bundled server at it. The file holds KEY=VALUE lines (# comments, optional matching quotes; no export, interpolation or multi-line values). Only UNIFI_* keys are accepted, and each behaves exactly as if exported, including _FILE / _COMMAND providers and policy gates. Variables already in the process environment win. A missing file is not an error. On POSIX the file must be owned by you and not group- or world-writable (keep it chmod 600); Windows has no mode check, so keep it in your user profile.

To keep the secret out of the MCP client's environment (and out of every process the client spawns), set UNIFI_PASSWORD_FILE to a path whose contents are the password, or UNIFI_PASSWORD_COMMAND to an absolute argv whose stdout is the password (contract). The same _FILE / _COMMAND suffixes work on UNIFI_API_KEY and on the per-server variables below. Details are in each server's docs/configuration.md.

Multi-controller setups

Each server supports its own prefixed environment variables that take priority over the shared UNIFI_* variables. This lets you point the Network and Protect servers at different controllers (or different credentials) while keeping a single trusted env file explicitly loaded by the launcher.

Credentials follow the host. The shared username, password and API key (rows marked †) are used only when the server has no host of its own, or its host and port name the same console as UNIFI_HOST (compared as written apart from letter case: no scheme, slash or space is stripped, and an IP address and a hostname for the same console count as different). A server pointed at another host takes its credentials from its own variables, and logs at startup which shared variable it ignored. Older releases sent the shared credentials to any host, so give a server on another host its own credentials. The other rows always fall back. Details: credential providers.

Shared (fallback)Network serverProtect serverAccess server
UNIFI_HOSTUNIFI_NETWORK_HOSTUNIFI_PROTECT_HOSTUNIFI_ACCESS_HOST
UNIFI_USERNAME †UNIFI_NETWORK_USERNAMEUNIFI_PROTECT_USERNAMEUNIFI_ACCESS_USERNAME
UNIFI_PASSWORD †UNIFI_NETWORK_PASSWORDUNIFI_PROTECT_PASSWORDUNIFI_ACCESS_PASSWORD
UNIFI_PORTUNIFI_NETWORK_PORTUNIFI_PROTECT_PORTUNIFI_ACCESS_PORT
UNIFI_VERIFY_SSLUNIFI_NETWORK_VERIFY_SSLUNIFI_PROTECT_VERIFY_SSLUNIFI_ACCESS_VERIFY_SSL
UNIFI_SSL_FINGERPRINTUNIFI_NETWORK_SSL_FINGERPRINTUNIFI_PROTECT_SSL_FINGERPRINTUNIFI_ACCESS_SSL_FINGERPRINT
UNIFI_API_KEY †UNIFI_NETWORK_API_KEYUNIFI_PROTECT_API_KEYUNIFI_ACCESS_API_KEY

Single controller? Just set the shared UNIFI_* variables -- all servers will use them. Server-specific variables are only needed when the servers talk to different controllers or use different credentials; a server whose host differs from UNIFI_HOST needs its own credentials as well.

Site Manager has no shared fallback. Its only credential is UNIFI_SITEMANAGER_API_KEY, or its _FILE / _COMMAND form (set exactly one). It never reads UNIFI_API_KEY, any other shared UNIFI_* variable, config.yaml or CONFIG_PATH, and it takes no host, username or password. A console key and a Site Manager key reach different places, so neither is ever sent to the other's destination. See Site Manager configuration.

InnerSpace uses a console login. It takes a host, username and password like the other console servers, but has no API key setting and never reads UNIFI_API_KEY. See InnerSpace configuration.

Controller operation gate: The Network, Protect and Access servers run confirmed writes to their controller one at a time, in the order they arrive (direct calls, *_execute and *_batch alike), and cap concurrent reads. The InnerSpace server caps its reads the same way. UNIFI_WRITE_HOLD_SECONDS (default 120), UNIFI_CALL_WAIT_SECONDS (25) and UNIFI_READ_CONCURRENCY (8) tune it, with per-server overrides such as UNIFI_NETWORK_READ_CONCURRENCY. A call refused as busy sends nothing to the controller and says so. The guarantee is per server process. See each server's configuration page.

Tracing: Set OTEL_EXPORTER_OTLP_ENDPOINT to export the MCP SDK's spans over OTLP, one per MCP message, continuing a trace context passed in the request's _meta. The Docker images include the exporter; pip and uvx installs need the otel extra (for example unifi-network-mcp[otel]). Off by default.

For the full configuration reference including permissions, transports, and advanced options, see the Network server docs, Protect server docs, Access server docs, Site Manager server docs, or InnerSpace server docs.

Secret redaction

Tool and API responses redact known controller secret fields by default — Wi-Fi passphrases, VPN private/preshared keys, whole VPN config blobs (imported WireGuard/OpenVPN .conf/.ovpn files), API tokens, SNMP community strings, SNMPv3 passwords, device-SSH credentials and the management key, and Access credential token/PIN values come back as ***REDACTED***. This keeps secrets out of agent context and logs.

When a trusted local administration workflow genuinely needs raw values, disable redaction for that process with UNIFI_REDACT_SENSITIVE_FIELDS=false or a server-specific override such as UNIFI_NETWORK_REDACT_SENSITIVE_FIELDS=false, UNIFI_PROTECT_REDACT_SENSITIVE_FIELDS=false, UNIFI_ACCESS_REDACT_SENSITIVE_FIELDS=false, UNIFI_SITEMANAGER_REDACT_SENSITIVE_FIELDS=false, UNIFI_INNERSPACE_REDACT_SENSITIVE_FIELDS=false, or UNIFI_API_REDACT_SENSITIVE_FIELDS=false. To keep an existing secret during an update, simply omit the field — do not pass the ***REDACTED*** marker back; doing so is rejected so the placeholder can never be written as a real secret. See PRIVACY.md for the full list of redacted fields.

Agent Skills

Each plugin ships with agent skills that go beyond raw tool access — they teach agents how to perform common tasks effectively:

SkillPluginWhat it does
Network Health Checkunifi-networkBatch diagnostics across devices, health subsystems, and alarms with reference docs for interpreting results
Firewall Managerunifi-networkNatural language firewall management with policy templates, config snapshots, and change tracking
Firewall Auditorunifi-networkSecurity audit with 16 benchmarks, 100-point scoring, topology analysis, and trend tracking
Security Digestunifi-protectProtect event summary with explicit coverage limits; optional Access and Network reads add correlation hypotheses
UniFi Accessunifi-accessDoor control, credentials, visitors, access policies — with real-time event streaming and activity summaries
Incident Investigationunifi-intelligenceOne Network device incident with Protect camera context, from the read-only incident evidence tools, with cited coverage
Security Patrolunifi-intelligenceArea activity from the cloud worker's merged location timeline
Visitor Auditunifi-intelligenceAccess events beside Network evidence from the cloud worker's timeline, with identity limits

Skills include reference documentation for device states, alarm types, firewall schemas, and event fields. The agent gathers and interprets evidence; the firewall score CLI computes scores from supported findings. Firewall snapshots, diffs, and template application follow the skill instructions.

Each non-setup skill declares required and optional servers and requires a Coverage and Limitations section in reports. Missing required dependencies stop the workflow; optional missing sources, failed reads, and result caps are disclosed. Security Patrol and Visitor Audit need the cloud worker's merged timeline through a connected relay; see Cross-Product Capabilities.

Architecture

This is a monorepo with shared packages:

apps/
  network/          # UniFi Network MCP server (stable, 217 tools)
  protect/          # UniFi Protect MCP server (stable, 68 tools)
  access/           # UniFi Access MCP server (stable, 38 tools)
  sitemanager/      # UniFi Site Manager MCP server (beta, cloud, read-only, 9 tools)
  innerspace/       # UniFi InnerSpace MCP server (console login, read-only, 9 tools; not yet released)
  api/              # Independent REST + GraphQL API server (beta)
  worker/           # Cloudflare Worker gateway + npm CLI
packages/
  unifi-core/       # Shared UniFi connectivity (auth, detection, retry)
  unifi-mcp-shared/ # Shared MCP patterns (permissions, tools, diagnostics, config)
  unifi-mcp-relay/  # Cloud relay sidecar (bridges local servers to Cloudflare Worker)
plugins/
  unifi-network/    # Claude Code/Codex/OpenClaw plugin: MCP server + agent skills + setup
  unifi-protect/    # Claude Code/Codex/OpenClaw plugin: MCP server + agent skills + setup
  unifi-access/     # Claude Code/Codex/OpenClaw plugin: MCP server + agent skills + setup
  unifi-intelligence/ # Skills-only plugin; needs unifi-network and unifi-protect
skills/
  _shared/          # Shared utilities for skill scripts (MCP client, config)
docs/               # Ecosystem-level documentation

Each Python server in apps/ is an independent package that depends on the shared packages. apps/worker/ is intentionally separate: it is a self-contained TypeScript/Node app for the Cloudflare Worker gateway and npm CLI. Keeping it in this repo lets relay protocol changes and worker contract tests move together.

See docs/ARCHITECTURE.md for details.

Development

make sync   # Install Python workspace + worker npm dependencies
make check  # Format check + lint + generated drift checks + tests + worker typecheck
make build  # Build deployable artifacts, including worker typecheck

Contributing

See CONTRIBUTING.md for the development workflow, including how to work with the monorepo, run tests, and submit PRs.

Support the Project

UniFi MCP is maintained as an independent open-source project. Sponsorship helps cover the ongoing AI costs behind building, testing, and maintaining the project, plus live controller compatibility testing, release maintenance, documentation, and issue triage across the Network, Protect, Access, Site Manager, API, relay, and plugin packages.

For a reproducible Network, Protect, or Access MCP problem, if the server can start and register tools, generate and review an optional sanitized support bundle before opening a public bug report. If it cannot, use the bug report's manual form fields instead. The Site Manager and InnerSpace servers have no support-bundle tool; follow their Site Manager or InnerSpace troubleshooting guide and use the manual fields. Support bundles are safer than ordinary diagnostic logs but remain sanitized, not anonymous.

License

MIT

Details

Marketplace
sirkirby/unifi-mcp
Source
plugins/unifi-sitemanager
Category
Networking
License
MIT
Keywords
unifi, sitemanager, cloud, read-only, mcp

More from sirkirby/unifi-mcp

All 5

Similar to unifi-sitemanager

More DevOps & Cloud