Skip to content
Back to search

unifi-plugins

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 14 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sirkirby/unifi-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sirkirby/unifi-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sirkirby--unifi-mcp/badge.svg)](/listings/sirkirby--unifi-mcp)

HTML

<a href="/listings/sirkirby--unifi-mcp"><img src="/api/listings/sirkirby--unifi-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](CHANGELOG.md) for what each plugin release changed, and the [plugin upgrade guide](docs/plugin-upgrade.md) 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](docs/plugin-upgrade.md) for update steps.

Prerequisites, version boundaries and verification status for each client are in the [plugin support matrix](docs/plugin-support.md).

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 57 lines
  1. {
  2. "name": "unifi-plugins",
  3. "owner": {
  4. "name": "sirkirby",
  5. "email": "unifi@privatly.net"
  6. },
  7. "metadata": {
  8. "description": "UniFi MCP plugins — manage Ubiquiti UniFi infrastructure from Claude Code, Codex, and OpenClaw"
  9. },
  10. "plugins": [
  11. {
  12. "name": "unifi-network",
  13. "source": "./plugins/unifi-network",
  14. "description": "UniFi Network MCP server — manage network devices, clients, firewall, VPN, and more",
  15. "license": "MIT",
  16. "keywords": ["unifi", "network", "firewall", "wifi", "mcp"],
  17. "category": "networking",
  18. "repository": "https://github.com/sirkirby/unifi-mcp"
  19. },
  20. {
  21. "name": "unifi-protect",
  22. "source": "./plugins/unifi-protect",
  23. "description": "UniFi Protect MCP server — manage security cameras, NVR, recordings, and smart detections",
  24. "license": "MIT",
  25. "keywords": ["unifi", "protect", "cameras", "nvr", "security", "mcp"],
  26. "category": "networking",
  27. "repository": "https://github.com/sirkirby/unifi-mcp"
  28. },
  29. {
  30. "name": "unifi-access",
  31. "source": "./plugins/unifi-access",
  32. "description": "UniFi Access MCP server — manage door locks, credentials, visitors, and access policies",
  33. "license": "MIT",
  34. "keywords": ["unifi", "access", "doors", "credentials", "mcp"],
  35. "category": "networking",
  36. "repository": "https://github.com/sirkirby/unifi-mcp"
  37. },
  38. {
  39. "name": "unifi-sitemanager",
  40. "source": "./plugins/unifi-sitemanager",
  41. "description": "Read-only UniFi Site Manager cloud inventory, ISP metrics and SD-WAN across the whole account",
  42. "license": "MIT",
  43. "keywords": ["unifi", "sitemanager", "cloud", "read-only", "mcp"],
  44. "category": "networking",
  45. "repository": "https://github.com/sirkirby/unifi-mcp"
  46. },
  47. {
  48. "name": "unifi-intelligence",
  49. "source": "./plugins/unifi-intelligence",
  50. "description": "UniFi Intelligence skills — investigate Network device incidents with Protect camera context; requires the unifi-network and unifi-protect plugins",
  51. "license": "MIT",
  52. "keywords": ["unifi", "incident", "investigation", "security", "network", "protect"],
  53. "category": "networking",
  54. "repository": "https://github.com/sirkirby/unifi-mcp"
  55. }
  56. ]
  57. }
README.md · README · 437 lines
  1. # UniFi MCP
  2. <p align="center">
  3. <img src="docs/assets/hero-readme.jpg" alt="UniFi MCP — AI agents for your UniFi infrastructure" width="720">
  4. </p>
  5. Leverage agents and agentic AI workflows to manage your UniFi deployment.
  6. [![PyPI - Network](https://img.shields.io/pypi/v/unifi-network-mcp)](https://pypi.org/project/unifi-network-mcp/)
  7. [![PyPI - Protect](https://img.shields.io/pypi/v/unifi-protect-mcp)](https://pypi.org/project/unifi-protect-mcp/)
  8. [![PyPI - Access](https://img.shields.io/pypi/v/unifi-access-mcp)](https://pypi.org/project/unifi-access-mcp/)
  9. [![PyPI - Site Manager](https://img.shields.io/pypi/v/unifi-sitemanager-mcp)](https://pypi.org/project/unifi-sitemanager-mcp/)
  10. [![PyPI - Relay](https://img.shields.io/pypi/v/unifi-mcp-relay)](https://pypi.org/project/unifi-mcp-relay/)
  11. [![PyPI - API Server](https://img.shields.io/pypi/v/unifi-api-server)](https://pypi.org/project/unifi-api-server/)
  12. [![npm - Worker](https://img.shields.io/npm/v/unifi-mcp-worker)](https://www.npmjs.com/package/unifi-mcp-worker)
  13. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  14. [![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
  15. ## Servers
  16. | Server | Status | Tools | Package |
  17. |--------|--------|-------|---------|
  18. | [Network](apps/network/) | Stable | 210 | [`unifi-network-mcp`](https://pypi.org/project/unifi-network-mcp/) |
  19. | [Protect](apps/protect/) | Stable | 65 | [`unifi-protect-mcp`](https://pypi.org/project/unifi-protect-mcp/) |
  20. | [Access](apps/access/) | Stable | 37 | [`unifi-access-mcp`](https://pypi.org/project/unifi-access-mcp/) |
  21. | [Site Manager](apps/sitemanager/) | Beta | 9 | [`unifi-sitemanager-mcp`](https://pypi.org/project/unifi-sitemanager-mcp/) |
  22. Network, Protect and Access each connect to a console you name on your network. Site Manager is different: it reads Ubiquiti's cloud [Site Manager API](https://developer.ui.com/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.
  23. ## Plugins
  24. Install these from the Claude Code, Codex or OpenClaw marketplace; [Quick Start](#quick-start) shows how.
  25. | Plugin | What you get |
  26. |--------|--------------|
  27. | `unifi-network` | The Network MCP server, its agent skills and guided setup |
  28. | `unifi-protect` | The Protect MCP server, its agent skills and guided setup |
  29. | `unifi-access` | The Access MCP server, its agent skills and guided setup |
  30. | `unifi-sitemanager` | The Site Manager MCP server for a whole UI account, its agent skills and guided key setup |
  31. | `unifi-intelligence` | Cross-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](#cloud-relay). It requires the Network and Protect plugins |
  32. The [Agent Skills](#agent-skills) table lists every skill each plugin ships.
  33. ## Choose an integration
  34. | What you are building | Use | Why |
  35. |-----------------------|-----|-----|
  36. | An AI assistant or another existing MCP client | [Network](apps/network/), [Protect](apps/protect/), or [Access](apps/access/) MCP server | Standard MCP discovery, tool calls, permissions, and confirmation flows |
  37. | An account-wide view of every console, site and device on a UI account | [Site Manager](apps/sitemanager/) MCP server | Read-only inventory, WAN health and SD-WAN status from Ubiquiti's cloud with one Site Manager API key |
  38. | A custom application, automation service, code-execution runtime, or MCP adapter | [`unifi-api-server`](apps/api/) | Your code controls call sequencing, data joins, resource limits, and approval flow |
  39. | Remote access for an MCP client | [Cloud Relay](packages/unifi-mcp-relay/) | Authenticated remote MCP routing without exposing the local servers directly |
  40. An MCP adapter can expose a small set of tools while using `unifi-api-server`
  41. as its backend. This keeps application-specific joins, branching, loops, and
  42. code isolation out of the general-purpose MCP servers.
  43. ## Cloud Relay
  44. | Component | Status | Package |
  45. |-----------|--------|---------|
  46. | [Relay Sidecar](https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-mcp-relay) | Beta | [`unifi-mcp-relay`](https://pypi.org/project/unifi-mcp-relay/) |
  47. | [Worker Gateway](https://github.com/sirkirby/unifi-mcp/tree/main/apps/worker) | Beta | [`unifi-mcp-worker`](https://www.npmjs.com/package/unifi-mcp-worker) (CLI) |
  48. 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](packages/unifi-mcp-relay/) to connect local servers.
  49. ## REST + GraphQL API
  50. | Component | Status | Package |
  51. |-----------|--------|---------|
  52. | [API Server](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api) | Beta | [`unifi-api-server`](https://pypi.org/project/unifi-api-server/) · [GHCR image](https://github.com/sirkirby/unifi-mcp/pkgs/container/unifi-api-server) |
  53. `unifi-api-server` is an independent HTTP service for custom applications,
  54. automation, and adapters. It provides typed REST resources, read-only GraphQL
  55. queries, SSE streams, scoped API keys and administration, plus a REST action
  56. endpoint for supported controller operations. It shares `unifi-core` managers
  57. with the MCP servers but does not proxy or require them.
  58. The API server also serves the nine Site Manager reads once an administrator
  59. adds one account-level cloud connection. Every API key with the `read` scope
  60. can then read the whole cloud account; see
  61. [Site Manager cloud connection](apps/api/README.md#site-manager-cloud-connection).
  62. See [`apps/api/README.md`](apps/api/README.md) for quick-start and deployment patterns.
  63. ## What is this?
  64. UniFi MCP is a collection of [Model Context Protocol](https://modelcontextprotocol.io/) 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.
  65. 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](apps/sitemanager/) and the [privacy policy](PRIVACY.md#site-manager-cloud-requests).
  66. ## MCP HTTP Access
  67. 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](apps/network/docs/transports.md#http-bearer-token)). 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 starts only with the opt-in `sitemanager` profile. Use an authenticated TLS proxy or Cloud Relay for remote access, and prevent direct access to the backend. See the [transport security model](SECURITY.md#mcp-transport-trust-boundary) and [HTTP setup and migration](apps/network/docs/transports.md#http-deployment-security).
  68. | Setting | Default | Purpose |
  69. |---------|---------|---------|
  70. | `UNIFI_MCP_HTTP_ENABLED` | `false` | Opt into HTTP transport |
  71. | `UNIFI_MCP_HOST` | `127.0.0.1` | Bind address; Compose explicitly uses `0.0.0.0` inside containers |
  72. | `UNIFI_MCP_HTTP_FORCE` | `false` | Allow HTTP outside container PID 1 |
  73. | `UNIFI_MCP_ALLOWED_HOSTS` | `localhost,127.0.0.1` | Complete 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 |
  74. | `UNIFI_MCP_ENABLE_DNS_REBINDING_PROTECTION` | `true` | Validate Host headers to prevent DNS-rebinding requests |
  75. | `UNIFI_MCP_HTTP_AUTH_TOKEN` | unset | Require `Authorization: Bearer <token>` on every HTTP request; at least 32 printable ASCII characters. `UNIFI_<NETWORK\|PROTECT\|ACCESS\|SITEMANAGER>_MCP_HTTP_AUTH_TOKEN` overrides it per server, and `_FILE`/`_COMMAND` spellings work. Set but empty refuses startup |
  76. ## MCP Discovery
  77. 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.
  78. The lazy-loading meta-tools — `*_tool_index`, `*_execute`, `*_batch`, `*_batch_status`, 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](docs/tool-index.md) for mode-by-mode behavior.
  79. ## MCP response size
  80. 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.
  81. 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`.
  82. `UNIFI_NETWORK_MCP_CONTENT_MODE`, `UNIFI_PROTECT_MCP_CONTENT_MODE`, `UNIFI_ACCESS_MCP_CONTENT_MODE`, and `UNIFI_SITEMANAGER_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.
  83. ## Quick Start
  84. ### Install with your agent
  85. Paste the block below into your coding agent. It points the agent at the
  86. canonical, versioned setup guide and limits what it may change:
  87. ```text
  88. Install UniFi MCP for me using the official instructions at:
  89. https://github.com/sirkirby/unifi-mcp/blob/main/docs/agent-install.md
  90. Before changing anything, identify my agent client and operating system, ask
  91. whether I need Network, Protect, Access, or more than one, and show me the exact
  92. commands and configuration files you plan to change. Wait for my confirmation.
  93. Do not ask me to paste a password or API key into chat. Prefer an indirect
  94. credential provider or the client's secure secret prompt. Keep mutation
  95. permissions in confirm mode and explicitly deny create, update, and delete
  96. unless I opt in. After setup, reload the client, verify the MCP connection and
  97. tool list, and run one harmless read-only check.
  98. ```
  99. The guide covers native plugins, product-scoped `npx skills add` installs,
  100. OpenCode's built-in MCP support, and the current manual paths for Antigravity,
  101. Cursor, and Devin Desktop. A skills install adds agent guidance; it does not by
  102. itself register the MCP server.
  103. See the [changelog](CHANGELOG.md) for what each plugin release changed, and the
  104. [plugin upgrade guide](docs/plugin-upgrade.md) before updating an existing install.
  105. ### Claude Code (recommended)
  106. Install via the plugin marketplace — includes the MCP server, an agent skill, and guided setup:
  107. ```
  108. /plugin marketplace add sirkirby/unifi-mcp
  109. /plugin install unifi-network@unifi-plugins
  110. /unifi-network:unifi-network-setup
  111. ```
  112. Repeat for Protect or Access if needed:
  113. ```
  114. /plugin install unifi-protect@unifi-plugins
  115. /plugin install unifi-access@unifi-plugins
  116. ```
  117. 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.
  118. For the cross-product skills, `/plugin install unifi-intelligence@unifi-plugins`
  119. also installs the Network and Protect plugins it needs. Claude Code opens no
  120. options dialog for plugins it installs as dependencies, so run each product's
  121. setup command (`/unifi-network:unifi-network-setup`,
  122. `/unifi-protect:unifi-protect-setup`) for any not yet configured.
  123. `/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](docs/plugin-upgrade.md) for update steps.
  124. Prerequisites, version boundaries and verification status for each client are in the [plugin support matrix](docs/plugin-support.md).
  125. ### Codex
  126. Register the UniFi MCP marketplace, then install the plugins from Codex's `/plugins` UI:
  127. ```bash
  128. codex plugin marketplace add sirkirby/unifi-mcp
  129. ```
  130. 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:
  131. > Use the `unifi-network-setup` skill to configure this for Codex.
  132. 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](docs/plugin-upgrade.md#one-time-step-if-you-ran-codex-setup-before-100).
  133. ### UniFi account requirements
  134. 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.
  135. The Site Manager server needs no console account. It uses a Site Manager API key created at [unifi.ui.com](https://unifi.ui.com) under Settings > API Keys, which reads every console the UI account can see.
  136. ### OpenClaw
  137. OpenClaw can install the same UniFi plugin bundles from the marketplace and map their skills plus MCP server definitions into embedded Pi sessions:
  138. ```bash
  139. openclaw plugins install unifi-network --marketplace https://github.com/sirkirby/unifi-mcp
  140. openclaw gateway restart
  141. ```
  142. 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.
  143. 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](docs/credential-providers.md) so the secret never appears in the command line:
  144. ```bash
  145. bash ~/.openclaw/extensions/unifi-network/scripts/set-env.sh --target openclaw \
  146. UNIFI_NETWORK_HOST=192.168.1.1 \
  147. UNIFI_NETWORK_USERNAME=admin \
  148. 'UNIFI_NETWORK_PASSWORD_FILE=/absolute/path/to/password-file'
  149. ```
  150. 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](docs/plugin-upgrade.md#openclaw)). 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.
  151. ### Other MCP clients
  152. Run the servers directly:
  153. ```bash
  154. uvx unifi-network-mcp@latest
  155. uvx unifi-protect-mcp@latest
  156. uvx unifi-access-mcp@latest
  157. uvx unifi-sitemanager-mcp@latest
  158. ```
  159. For Claude Desktop, add to your `claude_desktop_config.json`:
  160. ```jsonc
  161. {
  162. "mcpServers": {
  163. "unifi-network": {
  164. "command": "uvx",
  165. "args": ["unifi-network-mcp@latest"],
  166. "env": {
  167. // Server-specific vars take priority; UNIFI_* is the fallback
  168. "UNIFI_NETWORK_HOST": "192.168.1.1",
  169. "UNIFI_NETWORK_USERNAME": "admin",
  170. "UNIFI_NETWORK_PASSWORD": "your-password"
  171. }
  172. },
  173. "unifi-protect": {
  174. "command": "uvx",
  175. "args": ["unifi-protect-mcp@latest"],
  176. "env": {
  177. "UNIFI_PROTECT_HOST": "192.168.1.1",
  178. "UNIFI_PROTECT_USERNAME": "admin",
  179. "UNIFI_PROTECT_PASSWORD": "your-password"
  180. }
  181. },
  182. "unifi-access": {
  183. "command": "uvx",
  184. "args": ["unifi-access-mcp@latest"],
  185. "env": {
  186. "UNIFI_ACCESS_HOST": "192.168.1.1",
  187. "UNIFI_ACCESS_USERNAME": "admin",
  188. "UNIFI_ACCESS_PASSWORD": "your-password"
  189. }
  190. }
  191. }
  192. }
  193. ```
  194. > **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.
  195. ### Site Manager
  196. Give the Site Manager server only its own key, in a file only you can read. It takes none of the console variables above:
  197. ```jsonc
  198. {
  199. "mcpServers": {
  200. "unifi-sitemanager": {
  201. "command": "uvx",
  202. "args": ["unifi-sitemanager-mcp@latest"],
  203. "env": {
  204. "UNIFI_SITEMANAGER_API_KEY_FILE": "/Users/you/.config/unifi-mcp/sitemanager-api-key"
  205. }
  206. }
  207. }
  208. }
  209. ```
  210. It uses stdio by default; HTTP is opt-in on port 3003. See the [Site Manager README](apps/sitemanager/README.md).
  211. ## Usage Examples
  212. Once connected, just ask your AI agent in natural language:
  213. **Network**
  214. > "Show me all clients on the Guest VLAN with their signal strength and data usage"
  215. > "Create a firewall rule that blocks IoT devices from reaching the internet between midnight and 6 AM"
  216. > "Audit my firewall policies — are there any redundant or conflicting rules?"
  217. > "Show me the top traffic flows from the last hour and group them by destination"
  218. **Protect**
  219. > "List all cameras that detected motion in the last hour"
  220. > "Show me smart detection events from the front door camera today — people and vehicles only"
  221. > "Find driveway detections for white vans this week"
  222. **Access**
  223. > "Who badged into the office today? Show me a timeline of all door access events"
  224. > "Create a visitor pass for John Smith with access to the main entrance tomorrow 9-5"
  225. **Site Manager**
  226. > "List every console on my UniFi account with its OS version and whether it is connected"
  227. > "Which sites had WAN downtime or high latency in the last 24 hours?"
  228. **UniFi Intelligence** (the `unifi-intelligence` plugin)
  229. > "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
  230. > "Show me everything that happened at the front entrance in the last hour" — needs the [cloud worker](apps/worker/) and [relay](packages/unifi-mcp-relay/)
  231. All mutations use a **preview-then-confirm** flow (Site Manager has none: every one of its tools reads) — you see exactly what will change before anything is applied.
  232. ## Configuration
  233. Set these variables in the server's process environment (shell exports, the MCP client's `env` block, or Docker `environment:` / `env_file:`):
  234. | Variable | Required | Description |
  235. |----------|----------|-------------|
  236. | `UNIFI_HOST` | Yes | Controller IP or hostname |
  237. | `UNIFI_USERNAME` | Yes | Local admin/service account username; do not use a Ubiquiti SSO account |
  238. | `UNIFI_PASSWORD` | Yes | Password for the local account |
  239. | `UNIFI_API_KEY` | No | UniFi API key for selected capabilities, including firewall policy ordering and some Protect settings updates |
  240. | `CONFIG_PATH` | No | Absolute path to an operator-controlled custom YAML file; otherwise uses bundled configuration |
  241. | `UNIFI_SETTINGS_FILE` | No | Absolute path (`~` allowed) to a per-user settings file of `UNIFI_*` variables; see below |
  242. | `UNIFI_DEFER_CONTROLLER_INIT` | No | Network 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 |
  243. | `UNIFI_META_TOOLS_ENABLED` | No | Network eager mode only: set `false` to omit indirect meta-tools; requires `UNIFI_ENABLED_CATEGORIES` or `UNIFI_ENABLED_TOOLS` |
  244. **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.
  245. **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.
  246. 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](docs/credential-providers.md)). 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`.
  247. ### Multi-controller setups
  248. 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:
  249. | Shared (fallback) | Network server | Protect server | Access server |
  250. |--------------------|----------------|----------------|---------------|
  251. | `UNIFI_HOST` | `UNIFI_NETWORK_HOST` | `UNIFI_PROTECT_HOST` | `UNIFI_ACCESS_HOST` |
  252. | `UNIFI_USERNAME` | `UNIFI_NETWORK_USERNAME` | `UNIFI_PROTECT_USERNAME` | `UNIFI_ACCESS_USERNAME` |
  253. | `UNIFI_PASSWORD` | `UNIFI_NETWORK_PASSWORD` | `UNIFI_PROTECT_PASSWORD` | `UNIFI_ACCESS_PASSWORD` |
  254. | `UNIFI_PORT` | `UNIFI_NETWORK_PORT` | `UNIFI_PROTECT_PORT` | `UNIFI_ACCESS_PORT` |
  255. | `UNIFI_VERIFY_SSL` | `UNIFI_NETWORK_VERIFY_SSL` | `UNIFI_PROTECT_VERIFY_SSL` | `UNIFI_ACCESS_VERIFY_SSL` |
  256. | `UNIFI_SSL_FINGERPRINT` | `UNIFI_NETWORK_SSL_FINGERPRINT` | `UNIFI_PROTECT_SSL_FINGERPRINT` | `UNIFI_ACCESS_SSL_FINGERPRINT` |
  257. | `UNIFI_API_KEY` | `UNIFI_NETWORK_API_KEY` | `UNIFI_PROTECT_API_KEY` | `UNIFI_ACCESS_API_KEY` |
  258. **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.
  259. **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](apps/sitemanager/docs/configuration.md).
  260. **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.
  261. For the full configuration reference including permissions, transports, and advanced options, see the [Network server docs](apps/network/docs/configuration.md), [Protect server docs](apps/protect/docs/configuration.md), [Access server docs](apps/access/docs/configuration.md), or [Site Manager server docs](apps/sitemanager/docs/configuration.md).
  262. ## Secret redaction
  263. 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.
  264. 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`, 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`](PRIVACY.md) for the full list of redacted fields.
  265. ## Agent Skills
  266. Each plugin ships with agent skills that go beyond raw tool access — they teach agents how to perform common tasks effectively:
  267. | Skill | Plugin | What it does |
  268. |-------|--------|-------------|
  269. | **Network Health Check** | unifi-network | Batch diagnostics across devices, health subsystems, and alarms with reference docs for interpreting results |
  270. | **Firewall Manager** | unifi-network | Natural language firewall management with policy templates, config snapshots, and change tracking |
  271. | **Firewall Auditor** | unifi-network | Security audit with 16 benchmarks, 100-point scoring, topology analysis, and trend tracking |
  272. | **Security Digest** | unifi-protect | Protect event summary with explicit coverage limits; optional Access and Network reads add correlation hypotheses |
  273. | **UniFi Access** | unifi-access | Door control, credentials, visitors, access policies — with real-time event streaming and activity summaries |
  274. | **Incident Investigation** | unifi-intelligence | One Network device incident with Protect camera context, from the read-only incident evidence tools, with cited coverage |
  275. | **Security Patrol** | unifi-intelligence | Area activity from the cloud worker's merged location timeline |
  276. | **Visitor Audit** | unifi-intelligence | Access events beside Network evidence from the cloud worker's timeline, with identity limits |
  277. 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.
  278. 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](docs/cross-product.md).
  279. ## Architecture
  280. This is a monorepo with shared packages:
  281. ```
  282. apps/
  283. network/ # UniFi Network MCP server (stable, 210 tools)
  284. protect/ # UniFi Protect MCP server (stable, 65 tools)
  285. access/ # UniFi Access MCP server (stable, 37 tools)
  286. sitemanager/ # UniFi Site Manager MCP server (beta, cloud, read-only, 9 tools)
  287. api/ # Independent REST + GraphQL API server (beta)
  288. worker/ # Cloudflare Worker gateway + npm CLI
  289. packages/
  290. unifi-core/ # Shared UniFi connectivity (auth, detection, retry)
  291. unifi-mcp-shared/ # Shared MCP patterns (permissions, tools, diagnostics, config)
  292. unifi-mcp-relay/ # Cloud relay sidecar (bridges local servers to Cloudflare Worker)
  293. plugins/
  294. unifi-network/ # Claude Code/Codex/OpenClaw plugin: MCP server + agent skills + setup
  295. unifi-protect/ # Claude Code/Codex/OpenClaw plugin: MCP server + agent skills + setup
  296. unifi-access/ # Claude Code/Codex/OpenClaw plugin: MCP server + agent skills + setup
  297. unifi-intelligence/ # Skills-only plugin; needs unifi-network and unifi-protect
  298. skills/
  299. _shared/ # Shared utilities for skill scripts (MCP client, config)
  300. docs/ # Ecosystem-level documentation
  301. ```
  302. 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.
  303. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.
  304. ## Development
  305. ```bash
  306. make sync # Install Python workspace + worker npm dependencies
  307. make check # Format check + lint + generated drift checks + tests + worker typecheck
  308. make build # Build deployable artifacts, including worker typecheck
  309. ```
  310. ## Contributing
  311. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, including how to work with the monorepo, run tests, and submit PRs.
  312. ## Support the Project
  313. 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.
  314. 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](docs/support-bundles.md) before opening a public bug report. If it cannot, use the bug report's manual form fields instead. The Site Manager server has no support-bundle tool; follow its [troubleshooting guide](apps/sitemanager/docs/troubleshooting.md) and use the manual fields. Support bundles are safer than ordinary diagnostic logs but remain sanitized, not anonymous.
  315. - [Sponsor on GitHub](https://github.com/sponsors/sirkirby)
  316. - [See what sponsorship funds](https://unifimcp.com/sponsor/)
  317. ## License
  318. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.