Skip to content
Back to search

unifi

Manage UniFi network infrastructure via the UniFi MCP Server. Use this skill for any task involving UniFi devices, clients, networks, VLANs, WiFi, firewall rules, zone-based firewall, VPNs, traffic monitoring, backups, RADIUS, QoS, DPI, port forwarding, ACLs, DHCP, DNS, or site management. Triggers when the user mentions UniFi, Ubiquiti, network clients, APs, switches, gateways, firewall policies, or traffic flows in a network management context.

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 11 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/enuno/unifi-mcp-server 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/enuno/unifi-mcp-server'

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/enuno--unifi-mcp-server/badge.svg)](/listings/enuno--unifi-mcp-server)

HTML

<a href="/listings/enuno--unifi-mcp-server"><img src="/api/listings/enuno--unifi-mcp-server/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.

1. Get an API key

1. Sign in to [UniFi Site Manager](https://unifi.ui.com). 2. Go to **Settings → Control Plane → Integrations** and choose **Create API Key**. 3. Copy the key. It is shown only once.

2. Install

pip install unifi-mcp-server          # or: uv tool install unifi-mcp-server
# Fleet mode extras (Postgres, Redis):
pip install 'unifi-mcp-server[fleet]'

Or use the container image (amd64, arm64 and arm/v7; the `-fleet` variant for amd64 and arm64):

docker pull ghcr.io/enuno/unifi-mcp-server:latest

3. Add it to your MCP client

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows), Cursor (`mcp.json`, from **View: Open MCP Settings**) and most other MCP clients take the same `mcpServers` block:

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["unifi-mcp-server"],
      "env": {
        "UNIFI_API_KEY": "your-api-key-here",
        "UNIFI_API_TYPE": "local",
        "UNIFI_LOCAL_HOST": "192.168.2.1"
      }
    }
  }
}

If you installed with `pip`, use `"command": "unifi-mcp-server"` and drop `args`. To run the container instead:

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "UNIFI_API_KEY=your-api-key-here",
        "-e", "UNIFI_API_TYPE=local",
        "-e", "UNIFI_LOCAL_HOST=192.168.2.1",
        "ghcr.io/enuno/unifi-mcp-server:latest"
      ]
    }
  }
}

Keep `-i` and do not add `-d`: the client talks to the server over the container's stdin and stdout.

4. Main settings

| Variable | Purpose | Default | |---|---|---| | `UNIFI_API_KEY` | UniFi API key (required) | — | | `UNIFI_API_TYPE` | `local`, `cloud-ea` or `cloud-v1` | `cloud-ea` | | `UNIFI_LOCAL_HOST` / `UNIFI_LOCAL_PORT` | Console address in `local` mode | — / `443` | | `UNIFI_LOCAL_VERIFY_SSL` | Verify the console's TLS certificate. `false` logs a warning at startup | `true` | | `UNIFI_LOCAL_CA_FILE` | CA certificate (PEM) for a self-signed console, instead of turning verification off | — | | `UNIFI_DEFAULT_SITE` | Site used when a tool call names none | `default` | | `UNIFI_SITE_MANAGER_ENABLED` | Enable the cloud tools (Site Manager, Mobility, InnerSpace, Carrier) | `false` | | `UNIFI_PROFILE` | Register only one group of tools ([profiles](#tool-profiles-and-safety-controls)) | all | | `UNIFI_READ_ONLY` / `UNIFI_DRY_RUN` | Read-only or preview-only server | `false` | | `DEBUG` | Registers `debug_api_request` (raw GET/DELETE, destructive tier, removed by read-only). Leave unset in production | unset | | `MCP_SERVER_TRANSPORT` | `stdio`, `streamable_http`, `http` or `sse` | `stdio` | | `MCP_AUTH_TOKEN` | Bearer token, required on network transports; `viewer:<token>` (or `operator:`, `admin:`) limits a token's role | — | | `REDIS_URL` | Optional response cache | — | | `WEBHOOK_SECRET` | HMAC secret for incoming UniFi webhooks | — | | `DATABASE_URL` | Turns on fleet mode (Postgres) | — |

[.env.example](.env.example) lists every setting with comments, including audit logging, SIEM export, metrics, Supermemory and agnost.ai.

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.

README.md · README · 463 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/unifi-mcp-server-logo.png" alt="UniFi MCP Server logo" width="200" height="200">
  3. </p>
  4. <h1 align="center">UniFi MCP Server</h1>
  5. <p align="center">
  6. <strong>AI-native control of UniFi networks through the Model Context Protocol</strong>
  7. </p>
  8. <p align="center">
  9. [![CI](https://github.com/enuno/unifi-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/enuno/unifi-mcp-server/actions/workflows/ci.yml)
  10. [![Security](https://github.com/enuno/unifi-mcp-server/actions/workflows/security.yml/badge.svg)](https://github.com/enuno/unifi-mcp-server/actions/workflows/security.yml)
  11. [![codecov](https://codecov.io/github/enuno/unifi-mcp-server/graph/badge.svg?token=ZD314B59CE)](https://codecov.io/github/enuno/unifi-mcp-server)
  12. [![PyPI](https://img.shields.io/pypi/v/unifi-mcp-server.svg)](https://pypi.org/project/unifi-mcp-server/)
  13. [![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  14. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
  15. [![Documentation](https://img.shields.io/badge/docs-UniFi%20MCP-0D9373)](https://docs.hashgrid.net/)
  16. [![Ask DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-6E56CF)](https://deepwiki.com/enuno/unifi-mcp-server)
  17. </p>
  18. An MCP server that exposes UniFi Network, UniFi Protect and the UniFi cloud APIs (Site Manager, Mobility, InnerSpace, Carrier Fabric) as MCP tools, so AI agents can read and change UniFi infrastructure through one standard interface. It runs against one controller or, in fleet mode, many.
  19. **Current release: 0.9.0.** See [CHANGELOG.md](CHANGELOG.md) for what changed.
  20. ## Contents
  21. - [Features](#features)
  22. - [API modes](#api-modes)
  23. - [Quick start](#quick-start)
  24. - [Agent skills](#agent-skills)
  25. - [Tool profiles and safety controls](#tool-profiles-and-safety-controls)
  26. - [Network transports and deployment](#network-transports-and-deployment)
  27. - [Calling the server from code](#calling-the-server-from-code)
  28. - [Native MCP prompts](#native-mcp-prompts)
  29. - [Documentation](#documentation)
  30. - [Development](#development)
  31. ## Features
  32. 343 tools in local mode, from 60 modules.
  33. - **Network:** clients (search, block, reconnect), networks and VLANs, WiFi SSIDs, DHCP reservations, DNS, WAN, guest vouchers, QoS profiles and traffic routes, DPI statistics, traffic flows.
  34. - **Devices:** inventory, adoption, restart, locate, upgrade, radio settings, port profiles and per-port overrides, switching and stacks, topology export (JSON, GraphML, DOT), diagnostics, WiFi channel planning.
  35. - **Security:** legacy firewall rules and groups, zone-based firewall (zones, policies, zone matrix), ACL rules, traffic matching lists, port forwarding, VPN and site-to-site VPN, content filtering, RADIUS and the guest portal.
  36. - **Protect:** cameras, NVRs, views, events, sensors, lights, chimes, sirens, relays, speakers, alarm hubs and the alarm manager.
  37. - **Cloud:** Site Manager (hosts, sites, cross-site statistics), the connector proxy, Mobility workspaces and devices, InnerSpace floor plans and inventory, Carrier Fabric subscribers and service plans.
  38. - **Operations:** sites, backups (create, schedule, download, restore), events, multi-site aggregation, device migration between sites.
  39. - **Fleet mode** (optional, with Postgres and Redis): many controllers behind one server, a controller registry with encrypted credentials, server-issued tokens with roles, a shared read cache, several replicas and background workers, and `fleet_*` tools that read across controllers. See [MULTI_CONTROLLER.md](MULTI_CONTROLLER.md) and [docs/FLEET_SCALING_PLAN.md](docs/FLEET_SCALING_PLAN.md).
  40. - **Native prompts:** eight parameterised UniFi operational workflows (health check, client connectivity, WiFi performance, device investigation, firewall review, change planning, Protect health, fleet summary) exposed through the standard `prompts/list` and `prompts/get` operations. See [docs/PROMPTS.md](docs/PROMPTS.md).
  41. - **Safety:** every mutating tool needs `confirm=True` and supports `dry_run=True`, plus read-only and dry-run server modes, role-based access over risk tiers, and a hash-chained audit log (see [below](#tool-profiles-and-safety-controls)).
  42. - **A2A discovery and delegation:** an agent card built from the live tool registry, served at `/a2a/agent-card` and `/.well-known/agent-card.json`, plus a capability manifest and a delegation endpoint that runs a registered tool under the server's own role, confirmation and audit controls. See [A2A.md](A2A.md).
  43. - **Observability:** Prometheus `/metrics`, `/healthz`, SIEM export of audit records, optional Redis caching, webhooks with HMAC verification.
  44. ## API modes
  45. Set `UNIFI_API_TYPE` to choose how the server reaches UniFi.
  46. | Mode | What it reaches | Use it for |
  47. |---|---|---|
  48. | `local` (recommended) | Your UniFi console or gateway on the LAN (`UNIFI_LOCAL_HOST`) | Everything: device and client control, configuration, firewall, Protect |
  49. | `cloud-ea` | UniFi's Early Access cloud API | Sites and aggregate statistics; no per-device control or configuration |
  50. | `cloud-v1` | UniFi's stable v1 cloud API | Sites and aggregate statistics; no per-device control or configuration |
  51. The cloud tools (Site Manager, Mobility, InnerSpace, Carrier Fabric) call `api.ui.com` and are registered in every mode. Set `UNIFI_SITE_MANAGER_ENABLED=true` to use Site Manager tools; actual exposure also depends on the selected profile. The existing Site Manager SD-WAN config list/detail/status reads use the official v1.0.0 `/v1/sd-wan-configs` paths after the 2026-11-08 reconciliation; this does not implement typed destination/performance steering policies, policy writes, or prove live account interoperability (see [API.md](API.md) and [the gap reconciliation](docs/COMPETITOR_GAP_RECONCILIATION.md)).
  52. Zone-based firewall tools need UniFi Network 9.0 or later. Some documented UniFi endpoints do not exist on every firmware version; see [docs/UNIFI_API.md](docs/UNIFI_API.md).
  53. **UniFi Network 11 / UniFi OS 6:** compatible per released documentation, with four items pending live-controller verification — not yet a claim of full support. USG gateways and the classic, self-hosted Network Application Server are removed platform targets; `fleet_health` automatically flags any registered controller with a USG in its device inventory, but there is no API signal to auto-detect a classic Network Application Server, so label that controller instead (e.g. `deployment=classic-server`) and filter on it. Network 11 replaces the statistics engine and resets historical data, so the statistics tools (`get_historical_stats`, `get_speed_test_history`, `get_dpi_statistics`, `list_top_applications`, `get_client_dpi`) attach a `statistics_note` to every empty response — an empty history right after the upgrade is expected, not an outage. See [docs/NETWORK_11_COMPATIBILITY.md](docs/NETWORK_11_COMPATIBILITY.md) for the full compatibility matrix.
  54. ## Quick start
  55. ### 1. Get an API key
  56. 1. Sign in to [UniFi Site Manager](https://unifi.ui.com).
  57. 2. Go to **Settings → Control Plane → Integrations** and choose **Create API Key**.
  58. 3. Copy the key. It is shown only once.
  59. ### 2. Install
  60. ```bash
  61. pip install unifi-mcp-server # or: uv tool install unifi-mcp-server
  62. # Fleet mode extras (Postgres, Redis):
  63. pip install 'unifi-mcp-server[fleet]'
  64. ```
  65. Or use the container image (amd64, arm64 and arm/v7; the `-fleet` variant for amd64 and arm64):
  66. ```bash
  67. docker pull ghcr.io/enuno/unifi-mcp-server:latest
  68. ```
  69. ### 3. Add it to your MCP client
  70. Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows), Cursor (`mcp.json`, from **View: Open MCP Settings**) and most other MCP clients take the same `mcpServers` block:
  71. ```json
  72. {
  73. "mcpServers": {
  74. "unifi": {
  75. "command": "uvx",
  76. "args": ["unifi-mcp-server"],
  77. "env": {
  78. "UNIFI_API_KEY": "<your-api-key>",
  79. "UNIFI_API_TYPE": "local",
  80. "UNIFI_LOCAL_HOST": "192.168.2.1"
  81. }
  82. }
  83. }
  84. }
  85. ```
  86. If you installed with `pip`, use `"command": "unifi-mcp-server"` and drop `args`. To run the container instead:
  87. ```json
  88. {
  89. "mcpServers": {
  90. "unifi": {
  91. "command": "docker",
  92. "args": [
  93. "run", "-i", "--rm",
  94. "-e", "UNIFI_API_KEY=your-api-key-here",
  95. "-e", "UNIFI_API_TYPE=local",
  96. "-e", "UNIFI_LOCAL_HOST=192.168.2.1",
  97. "ghcr.io/enuno/unifi-mcp-server:latest"
  98. ]
  99. }
  100. }
  101. }
  102. ```
  103. Keep `-i` and do not add `-d`: the client talks to the server over the container's stdin and stdout.
  104. ### 4. Main settings
  105. | Variable | Purpose | Default |
  106. |---|---|---|
  107. | `UNIFI_API_KEY` | UniFi API key (required) | — |
  108. | `UNIFI_API_TYPE` | `local`, `cloud-ea` or `cloud-v1` | `cloud-ea` |
  109. | `UNIFI_LOCAL_HOST` / `UNIFI_LOCAL_PORT` | Console address in `local` mode | — / `443` |
  110. | `UNIFI_LOCAL_VERIFY_SSL` | Verify the console's TLS certificate. `false` logs a warning at startup | `true` |
  111. | `UNIFI_LOCAL_CA_FILE` | CA certificate (PEM) for a self-signed console, instead of turning verification off. Can be the console's own certificate | — |
  112. | `UNIFI_LOCAL_TLS_SERVER_NAME` | Name the console's certificate is checked against, when it is not `UNIFI_LOCAL_HOST`: `unifi.local` for UniFi OS's own certificate | — |
  113. | `UNIFI_DEFAULT_SITE` | Site used when a tool call names none | `default` |
  114. | `UNIFI_SITE_MANAGER_ENABLED` | Enable the cloud tools (Site Manager, Mobility, InnerSpace, Carrier) | `false` |
  115. | `UNIFI_PROFILE` | Register only one group of tools ([profiles](#tool-profiles-and-safety-controls)) | all |
  116. | `UNIFI_READ_ONLY` / `UNIFI_DRY_RUN` | Read-only or preview-only server | `false` |
  117. | `DEBUG` | Registers `debug_api_request` (raw GET/DELETE, destructive tier, removed by read-only). Leave unset in production | unset |
  118. | `MCP_SERVER_TRANSPORT` | `stdio`, `streamable_http`, `http` or `sse` | `stdio` |
  119. | `MCP_AUTH_TOKEN` | Bearer token, required on network transports; `viewer:<token>` (or `operator:`, `admin:`) limits a token's role | — |
  120. | `REDIS_URL` | Optional response cache | — |
  121. | `WEBHOOK_SECRET` | HMAC secret for incoming UniFi webhooks | — |
  122. | `DATABASE_URL` | Turns on fleet mode (Postgres) | — |
  123. [.env.example](.env.example) lists every setting with comments, including audit logging, SIEM export, metrics, Supermemory and agnost.ai.
  124. ## Agent skills
  125. The `skills/` directory holds agent skills: Markdown files an AI agent loads on demand, so it knows which UniFi tools exist and how to use them safely without keeping every tool definition in context. Each skill is a folder with a `SKILL.md`, in the layout Claude Code and other agents install.
  126. **Using the server (operator skills)**
  127. | Skill | Covers |
  128. |---|---|
  129. | [`unifi-network`](skills/unifi-network/SKILL.md) | Clients, networks and VLANs, WiFi, DHCP, DNS, WAN, vouchers |
  130. | [`unifi-devices`](skills/unifi-devices/SKILL.md) | Inventory, adoption, restarts and upgrades, ports, switching, topology |
  131. | [`unifi-security`](skills/unifi-security/SKILL.md) | Firewall rules and groups, zone-based firewall, ACLs, port forwarding, VPN |
  132. | [`unifi-system`](skills/unifi-system/SKILL.md) | Sites, backups, QoS, traffic flows, DPI, RADIUS, guest portal |
  133. | [`unifi-channel-planning`](skills/unifi-channel-planning/SKILL.md) | Low-interference WiFi channel plans from neighbor scans |
  134. | [`unifi-mcp-setup`](skills/unifi-mcp-setup/SKILL.md) | One-file overview of the whole server: install, env vars, API-mode matrix, `UNIFI_PROFILE` |
  135. **Changing this codebase (developer skills)**
  136. | Skill | Covers |
  137. |---|---|
  138. | [`unifi-mcp-tool-builder`](skills/unifi-mcp-tool-builder/SKILL.md) | Adding any MCP tool: model, function, registration, tests, docs |
  139. | [`unifi-network-config-tools`](skills/unifi-network-config-tools/SKILL.md) | Network configuration tools: URL spaces, site IDs, read-modify-write |
  140. | [`unifi-security-tools`](skills/unifi-security-tools/SKILL.md) | Firewall, ZBF, ACL and port forward tools, and their risk tiers |
  141. | [`unifi-protect-tools`](skills/unifi-protect-tools/SKILL.md) | The `protect_*` modules and the Protect client |
  142. | [`unifi-cloud-fleet-tools`](skills/unifi-cloud-fleet-tools/SKILL.md) | Cloud API tools and the fleet stack |
  143. ### Install
  144. Claude Code loads skills from `~/.claude/skills/<name>/SKILL.md` (every session) or `<project>/.claude/skills/<name>/SKILL.md` (one project). Copy the folders you want:
  145. ```bash
  146. git clone https://github.com/enuno/unifi-mcp-server.git
  147. cd unifi-mcp-server
  148. mkdir -p ~/.claude/skills
  149. # All operator skills
  150. cp -r skills/unifi-network skills/unifi-devices skills/unifi-security \
  151. skills/unifi-system skills/unifi-channel-planning ~/.claude/skills/
  152. # Or one skill
  153. cp -r skills/unifi-security ~/.claude/skills/
  154. # The one-file overview of the whole server
  155. cp -r skills/unifi-mcp-setup ~/.claude/skills/
  156. ```
  157. Note: `npx skills` (and similar package-skill installers) only install a
  158. `SKILL.md` at the repository root, not the folders under `skills/`. Install
  159. individual skills with the `cp -r skills/<name>` commands above instead of
  160. relying on a root-level skill file.
  161. Other agents that read the same `SKILL.md` format take the same folders; copy them into that agent's skills directory (Codex, for example, reads `.agents/skills/`). To update, pull and copy again. Inside this repository the developer skills are already installed for Claude Code (`.claude/skills/`) and Codex (`.agents/skills/`).
  162. ### Use
  163. You don't invoke a skill yourself. The agent reads each skill's description and loads the one that matches your request, then calls the MCP tools it describes, so the MCP server must also be configured in the same client. For example:
  164. - "Which clients are on the guest VLAN right now?" loads `unifi-network`.
  165. - "Audit the zone-based firewall for anything that allows WAN to LAN." loads `unifi-security`.
  166. - "Which APs share a 5 GHz channel with a neighbor? Propose a channel plan." loads `unifi-channel-planning`.
  167. If the agent doesn't pick a skill up, name it ("use the unifi-security skill"). Pair a skill with the matching `UNIFI_PROFILE` to keep the tool list small too. [docs/SKILLS.md](docs/SKILLS.md) has the full guide.
  168. ## Tool profiles and safety controls
  169. **Profiles.** `UNIFI_PROFILE` registers only one group of modules, so the client sees fewer tool definitions:
  170. | Profile | Tools | Covers |
  171. |---|---|---|
  172. | `network` | 48 | Clients, networks, WiFi, DHCP, DNS, WAN, vouchers, channel planning |
  173. | `devices` | 53 | Devices, control, migration, ports, switching, topology, diagnostics |
  174. | `security` | 47 | Firewall, ZBF, ACLs, port forwarding, VPN, content filtering |
  175. | `system` | 182 | Sites, backups, events, DPI, QoS, RADIUS, traffic flows, Protect, cloud |
  176. | `protect` | 75 | The Protect modules |
  177. | `mobility` / `innerspace` / `carrier` | 12 / 10 / 15 | One cloud API each |
  178. | `minimal` | 19 | Sites, clients, devices |
  179. Counts include the four fleet tools every profile gets. An unknown profile logs a warning and loads everything.
  180. **Safety controls.**
  181. - Every mutating tool requires `confirm=True`, and `dry_run=True` returns the change it would make without making it.
  182. - `UNIFI_READ_ONLY=true` leaves mutating tools out of the tool list entirely. `UNIFI_DRY_RUN=true` forces every mutating call into preview mode.
  183. - `DEBUG=true` adds `debug_api_request`, a raw GET or DELETE to any controller endpoint. It is a destructive-tier tool, a DELETE needs `confirm=True`, and read-only mode removes it. Leave `DEBUG` unset in production.
  184. - With tokens, each tool has a risk tier (`read`, `write`, `destructive`) and each role a set of tiers: `viewer` reads, `operator` writes, and `admin` can also run destructive tools, including deletes, restores, restarts, client blocking and firewall policy changes. See [API.md](API.md#access-control).
  185. - Mutations are written to a hash-chained JSON-lines audit log (Postgres in fleet mode), with optional field encryption and SIEM export. See [SECURITY.md](SECURITY.md).
  186. - Inputs are validated with Pydantic, and credentials are redacted from logs.
  187. ## Network transports and deployment
  188. `stdio` is the default and needs no port. To serve MCP over the network, use Streamable HTTP:
  189. ```bash
  190. export MCP_SERVER_TRANSPORT=streamable_http
  191. export MCP_SERVER_PORT=3000
  192. export MCP_AUTH_TOKEN=$(openssl rand -hex 32) # required on every network transport
  193. unifi-mcp-server
  194. # Listening on 127.0.0.1:3000; clients send Authorization: Bearer $MCP_AUTH_TOKEN
  195. ```
  196. Clients and MCP gateways then connect to `http://<host>:3000/mcp`. The server binds to `127.0.0.1` unless you set `MCP_SERVER_HOST`; put an authenticating TLS proxy in front before exposing it further. `http` also works. `sse` is deprecated: client proxies such as `mcp-remote` can race its initialize handshake ([#96](https://github.com/enuno/unifi-mcp-server/issues/96)).
  197. Container, with the published port on loopback:
  198. ```yaml
  199. services:
  200. unifi-mcp:
  201. image: ghcr.io/enuno/unifi-mcp-server:latest
  202. environment:
  203. UNIFI_API_KEY: your-api-key
  204. UNIFI_API_TYPE: local
  205. UNIFI_LOCAL_HOST: 192.168.2.1
  206. MCP_SERVER_TRANSPORT: streamable_http
  207. MCP_SERVER_PORT: 3000
  208. MCP_SERVER_HOST: 0.0.0.0 # inside the container only
  209. MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}
  210. ports:
  211. - "127.0.0.1:3000:3000"
  212. ```
  213. The repository's [docker-compose.yml](docker-compose.yml) adds Redis and the MCP Toolbox dashboard ([MCP_TOOLBOX.md](MCP_TOOLBOX.md)); copy `.env.docker.example` to `.env` and run `make compose-up`. That example starts read-only (`UNIFI_READ_ONLY=true`) with a `viewer` stdio caller (`UNIFI_STDIO_ROLE=viewer`); to allow changes, set `UNIFI_READ_ONLY=false` and raise `UNIFI_STDIO_ROLE` to `operator`, or `admin` for destructive changes.
  214. - **Ansible:** [deploy/ansible/](deploy/ansible/overview.md) deploys the server alone, a single-host fleet (server, worker, Redis, Postgres), or replicas behind nginx on several hosts. To have an AI agent run the deployment, start from a prompt in [docs/deploy-prompts/](docs/deploy-prompts/overview.md).
  215. - **Kubernetes:** [deploy/helm/unifi-mcp/](deploy/helm/unifi-mcp/overview.md) is a Helm chart for the server alone or in fleet mode with workers, taking every credential from an existing Secret.
  216. - **Local dev deployment (either method):** `make helm-deploy-local` or `make ansible-dev-deploy` build the current working tree — including uncommitted changes — tag it `local-<short-sha>[-dirty]`, and deploy it for real, instead of pulling or building from a published release. See the "Deploying from a local checkout" / "Local dev deployment" sections in the two overview docs above.
  217. ## Calling the server from code
  218. Any MCP client library works. With the [FastMCP](https://github.com/jlowin/fastmcp) client:
  219. ```python
  220. import asyncio
  221. from fastmcp import Client
  222. config = {
  223. "mcpServers": {
  224. "unifi": {
  225. "command": "unifi-mcp-server",
  226. "env": {
  227. "UNIFI_API_KEY": "<your-api-key>",
  228. "UNIFI_API_TYPE": "local",
  229. "UNIFI_LOCAL_HOST": "192.168.2.1",
  230. },
  231. }
  232. }
  233. }
  234. async def main() -> None:
  235. async with Client(config) as client:
  236. sites = await client.call_tool("list_sites", {})
  237. print(sites.data)
  238. clients = await client.call_tool("list_active_clients", {"site_id": "default"})
  239. print(clients.data)
  240. # Mutations need confirm=True; dry_run=True previews the change.
  241. preview = await client.call_tool(
  242. "create_firewall_zone",
  243. {"site_id": "default", "name": "IoT", "confirm": True, "dry_run": True},
  244. )
  245. print(preview.data)
  246. asyncio.run(main())
  247. ```
  248. `bin/unifi-cli` runs a single tool from a shell (`unifi-cli list-clients --site default`); see [docs/SKILLS.md](docs/SKILLS.md#binunifi-cli--cli-wrapper).
  249. ## Native MCP prompts
  250. Besides the tools, the server exposes eight parameterised UniFi operational
  251. workflows through the standard MCP prompts interface. A client discovers them
  252. with `prompts/list` and retrieves a rendered workflow brief with `prompts/get`.
  253. ```python
  254. import asyncio
  255. from fastmcp import Client
  256. config = {
  257. "mcpServers": {
  258. "unifi": {
  259. "command": "unifi-mcp-server",
  260. "env": {
  261. "UNIFI_API_KEY": "<your-api-key>",
  262. "UNIFI_API_TYPE": "local",
  263. "UNIFI_LOCAL_HOST": "192.168.2.1",
  264. },
  265. }
  266. }
  267. }
  268. async def main() -> None:
  269. async with Client(config) as client:
  270. for prompt in await client.list_prompts():
  271. print(prompt.name, prompt.description)
  272. result = await client.get_prompt(
  273. "network_health_check",
  274. {"site_id": "default", "focus": "wan"},
  275. )
  276. for message in result.messages:
  277. print(message.content.text)
  278. asyncio.run(main())
  279. ```
  280. The prompts are `network_health_check`, `troubleshoot_client_connectivity`,
  281. `troubleshoot_wifi_performance`, `investigate_device`,
  282. `review_firewall_policy`, `plan_network_change`, `protect_health_check` and
  283. `fleet_health_summary`. A workflow is advertised only when the tools it needs
  284. are registered on this server, so the prompt list follows the API mode, the
  285. profile and the read-only and dry-run settings.
  286. Retrieving a prompt does **not** run the workflow and grants no approval. The
  287. rendered text tells an agent which read tools to call and what to report; the
  288. agent calls the tools itself, and the server's role checks, `confirm` gate and
  289. audit trail still apply.
  290. Use `make inspect` to open the MCP Inspector and browse the prompts, or the
  291. MCPJungle CLI to check what the gateway forwards:
  292. ```bash
  293. mcpjungle list prompts --server unifi
  294. mcpjungle get prompt unifi__network_health_check --arg site_id=default
  295. ```
  296. A tools-only client will not display the prompts; that is a client limitation.
  297. There is no prompts-as-tools shim.
  298. See [docs/PROMPTS.md](docs/PROMPTS.md) for the full catalog, the availability
  299. matrix, the validation rules and the manual acceptance steps.
  300. ## Documentation
  301. | Document | Contents |
  302. |---|---|
  303. | [API.md](API.md) | Every MCP tool and resource, with parameters and examples |
  304. | [docs/PROMPTS.md](docs/PROMPTS.md) | The native MCP prompt catalog, with arguments and availability rules |
  305. | [A2A.md](A2A.md) | The agent card, the capability manifest and the delegation endpoint |
  306. | [docs/AUDIT_A2A_SKILLS.md](docs/AUDIT_A2A_SKILLS.md) | The A2A and skills audit: what was implemented, what was not, and why |
  307. | [docs/SKILLS.md](docs/SKILLS.md) | Agent skills, profiles and the CLI wrapper |
  308. | [docs/UNIFI_API.md](docs/UNIFI_API.md) | The UniFi endpoints behind the tools |
  309. | [MULTI_CONTROLLER.md](MULTI_CONTROLLER.md) | Fleet mode: controllers, tokens and roles |
  310. | [METRICS.md](METRICS.md), [WEBHOOK_SETUP.md](WEBHOOK_SETUP.md), [A2A.md](A2A.md) | Metrics, webhooks, the A2A agent endpoints |
  311. | [NETWORK_PLAYBOOK.md](NETWORK_PLAYBOOK.md), [HARBOR_SETUP.md](HARBOR_SETUP.md) | Operating runbooks |
  312. | [SECURITY.md](SECURITY.md) | Reporting vulnerabilities, audit logging and hardening |
  313. | [SPEC.md](SPEC.md), [DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md), [ROADMAP.md](ROADMAP.md) | Architecture target and roadmap |
  314. | [CHANGELOG.md](CHANGELOG.md), [docs/RELEASE_PROCESS.md](docs/RELEASE_PROCESS.md) | Release history and how releases are cut and published |
  315. ## Development
  316. ```bash
  317. git clone https://github.com/enuno/unifi-mcp-server.git
  318. cd unifi-mcp-server
  319. make install # uv sync from uv.lock with the dev extra (no activation needed)
  320. make hooks # pre-commit and commit-msg hooks
  321. cp .env.example .env # then set UNIFI_API_KEY and, for local mode, UNIFI_LOCAL_HOST
  322. make test # unit tests
  323. make ci # every blocking CI check: lint, typecheck, security, docs coverage, tests with the 80% gate
  324. make inspect # open the server in the MCP Inspector (needs Node.js)
  325. make help # list every target
  326. ```
  327. Without `make`, the same commands run through `uv run --locked`, for example `uv run --locked pytest tests/unit/ -m "not integration"`. Integration tests (`-m integration`) need real UniFi hardware.
  328. Layout: `src/main.py` builds the server, `src/tools/` holds the tool modules, `src/api/` the UniFi clients, `src/models/` the Pydantic models, `src/fleet/` the fleet stack, and `tests/unit/` the unit tests. [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md) describe the conventions in detail, and [commands.md](commands.md) lists the development commands.
  329. ## Contributing
  330. Contributions from people and AI coding agents are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
  331. 1. Fork the repository and create a branch.
  332. 2. Write tests first, keep new code at 80% coverage or better, and run `make ci`.
  333. 3. Use conventional commit messages (`feat: ...`, `fix: ...`) and open a pull request.
  334. Issues with `[Bug]` in the title opened by a maintainer or collaborator get an automated first analysis; other reports are triaged by hand ([details](CONTRIBUTING.md#automated-workflows)).
  335. ## Security
  336. Report vulnerabilities as described in [SECURITY.md](SECURITY.md). Never commit credentials.
  337. ## Acknowledgments
  338. - [sirkirby/unifi-network-mcp](https://github.com/sirkirby/unifi-network-mcp), the reference implementation
  339. - [MakeWithData's UniFi MCP guide](https://www.makewithdata.tech/p/build-a-mcp-server-for-ai-access)
  340. - [Model Context Protocol](https://modelcontextprotocol.io) and [FastMCP](https://github.com/jlowin/fastmcp)
  341. ## License
  342. Apache License 2.0. See [LICENSE](LICENSE).
  343. ## Links
  344. - Issues and discussions: [GitHub Issues](https://github.com/enuno/unifi-mcp-server/issues), [GitHub Discussions](https://github.com/enuno/unifi-mcp-server/discussions)
  345. - Releases: <https://github.com/enuno/unifi-mcp-server/releases>
  346. - PyPI: <https://pypi.org/project/unifi-mcp-server/>
  347. - Container images: <https://ghcr.io/enuno/unifi-mcp-server>
  348. - MCP Registry: search for `io.github.enuno/unifi-mcp-server` at <https://registry.modelcontextprotocol.io>
  349. [![Star History Chart](https://api.star-history.com/svg?repos=enuno/unifi-mcp-server&type=date&legend=top-left)](https://www.star-history.com/#enuno/unifi-mcp-server&type=date&legend=top-left)

Ratings and comments

Sign in to rate this skill.

Sign in

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