Unifi Mcp Server

io.github.enuno由 GitHub 帳號 enuno 發布v0.2.0更新於 Nov 10, 2026

An MCP server that leverages official UniFi API

概覽

AI 產生的概覽

把 UniFi Network、Protect 與雲端 API 包裝成工具的 MCP 伺服器,讓助理檢視並修改 UniFi 基礎設施。

可以做什麼
  • 搜尋、封鎖與重新連線用戶端;管理網路、VLAN、WiFi SSID、DHCP、DNS、WAN 與訪客憑證
  • 盤點、納管、重新啟動、升級與定位裝置;管理連接埠、交換、拓撲匯出與頻道規劃
  • 管理防火牆規則與區域、ACL、連接埠轉送、VPN、內容過濾與 RADIUS
  • 控制 Protect 攝影機、NVR、感測器、告警與喇叭
  • 讀取並管理雲端 Site Manager、Mobility、InnerSpace 與 Carrier Fabric 資源
  • 執行站點、備份、事件與多站點操作,並提供八個內建維運流程提示
適用情境
適合透過對話查詢 UniFi 部署狀況或執行網路變更,可針對單一控制器,也可在叢集模式下管理多個控制器。唯讀與試執行模式方便先稽核與規劃再動手。
執行需求
以 stdio 在本機執行(Python 套件或容器)。需要 UniFi API 金鑰,本機模式還需控制器位址;清單另列出 UNIFI_HOST、UNIFI_USERNAME 與 UNIFI_PASSWORD。需能連線控制器或 UniFi 雲端 API。叢集模式另需 Postgres 與 Redis。
安裝前請注意
工具會改動基礎設施:防火牆政策、重新啟動、升級、封鎖用戶端、備份與還原。變更需 confirm=True 並支援 dry_run,唯讀與角色制模式可加以限制。DEBUG 會加入原始 GET/DELETE 工具,正式環境應保持關閉。憑證與 API 金鑰不可寫入日誌或程式碼儲存庫。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Unifi Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

[UniFi MCP Server logo]

UniFi MCP Server

AI-native control of UniFi networks through the Model Context Protocol

[CI] [Security] [codecov] [PyPI] [Python] [License] [Documentation] [Ask DeepWiki]

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.

Current release: 0.9.0. See CHANGELOG.md for what changed.

Contents

Features

343 tools in local mode, from 60 modules.

  • 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.
  • 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.
  • 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.
  • Protect: cameras, NVRs, views, events, sensors, lights, chimes, sirens, relays, speakers, alarm hubs and the alarm manager.
  • 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.
  • Operations: sites, backups (create, schedule, download, restore), events, multi-site aggregation, device migration between sites.
  • 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 and docs/FLEET_SCALING_PLAN.md.
  • 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.
  • 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).
  • 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.
  • Observability: Prometheus /metrics, /healthz, SIEM export of audit records, optional Redis caching, webhooks with HMAC verification.

API modes

Set UNIFI_API_TYPE to choose how the server reaches UniFi.

ModeWhat it reachesUse it for
local (recommended)Your UniFi console or gateway on the LAN (UNIFI_LOCAL_HOST)Everything: device and client control, configuration, firewall, Protect
cloud-eaUniFi's Early Access cloud APISites and aggregate statistics; no per-device control or configuration
cloud-v1UniFi's stable v1 cloud APISites and aggregate statistics; no per-device control or configuration

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 and the gap reconciliation).

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.

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 for the full compatibility matrix.

Quick start

1. Get an API key

  1. Sign in to UniFi Site Manager.
  2. Go to Settings → Control Plane → Integrations and choose Create API Key.
  3. Copy the key. It is shown only once.

2. Install

bash
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):

bash
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:

json
{  "mcpServers": {    "unifi": {      "command": "uvx",      "args": ["unifi-mcp-server"],      "env": {        "UNIFI_API_KEY": "<your-api-key>",        "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:

json
{  "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

VariablePurposeDefault
UNIFI_API_KEYUniFi API key (required)—
UNIFI_API_TYPElocal, cloud-ea or cloud-v1cloud-ea
UNIFI_LOCAL_HOST / UNIFI_LOCAL_PORTConsole address in local mode— / 443
UNIFI_LOCAL_VERIFY_SSLVerify the console's TLS certificate. false logs a warning at startuptrue
UNIFI_LOCAL_CA_FILECA certificate (PEM) for a self-signed console, instead of turning verification off. Can be the console's own certificate—
UNIFI_LOCAL_TLS_SERVER_NAMEName the console's certificate is checked against, when it is not UNIFI_LOCAL_HOST: unifi.local for UniFi OS's own certificate—
UNIFI_DEFAULT_SITESite used when a tool call names nonedefault
UNIFI_SITE_MANAGER_ENABLEDEnable the cloud tools (Site Manager, Mobility, InnerSpace, Carrier)false
UNIFI_PROFILERegister only one group of tools (profiles)all
UNIFI_READ_ONLY / UNIFI_DRY_RUNRead-only or preview-only serverfalse
DEBUGRegisters debug_api_request (raw GET/DELETE, destructive tier, removed by read-only). Leave unset in productionunset
MCP_SERVER_TRANSPORTstdio, streamable_http, http or ssestdio
MCP_AUTH_TOKENBearer token, required on network transports; viewer:<token> (or operator:, admin:) limits a token's role—
REDIS_URLOptional response cache—
WEBHOOK_SECRETHMAC secret for incoming UniFi webhooks—
DATABASE_URLTurns on fleet mode (Postgres)—

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

Agent skills

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.

Using the server (operator skills)

SkillCovers
unifi-networkClients, networks and VLANs, WiFi, DHCP, DNS, WAN, vouchers
unifi-devicesInventory, adoption, restarts and upgrades, ports, switching, topology
unifi-securityFirewall rules and groups, zone-based firewall, ACLs, port forwarding, VPN
unifi-systemSites, backups, QoS, traffic flows, DPI, RADIUS, guest portal
unifi-channel-planningLow-interference WiFi channel plans from neighbor scans
unifi-mcp-setupOne-file overview of the whole server: install, env vars, API-mode matrix, UNIFI_PROFILE

Changing this codebase (developer skills)

SkillCovers
unifi-mcp-tool-builderAdding any MCP tool: model, function, registration, tests, docs
unifi-network-config-toolsNetwork configuration tools: URL spaces, site IDs, read-modify-write
unifi-security-toolsFirewall, ZBF, ACL and port forward tools, and their risk tiers
unifi-protect-toolsThe protect_* modules and the Protect client
unifi-cloud-fleet-toolsCloud API tools and the fleet stack

Install

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:

bash
git clone https://github.com/enuno/unifi-mcp-server.gitcd unifi-mcp-servermkdir -p ~/.claude/skills
# All operator skillscp -r skills/unifi-network skills/unifi-devices skills/unifi-security \      skills/unifi-system skills/unifi-channel-planning ~/.claude/skills/
# Or one skillcp -r skills/unifi-security ~/.claude/skills/
# The one-file overview of the whole servercp -r skills/unifi-mcp-setup ~/.claude/skills/

Note: npx skills (and similar package-skill installers) only install a SKILL.md at the repository root, not the folders under skills/. Install individual skills with the cp -r skills/<name> commands above instead of relying on a root-level skill file.

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/).

Use

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:

  • "Which clients are on the guest VLAN right now?" loads unifi-network.
  • "Audit the zone-based firewall for anything that allows WAN to LAN." loads unifi-security.
  • "Which APs share a 5 GHz channel with a neighbor? Propose a channel plan." loads unifi-channel-planning.

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 has the full guide.

Tool profiles and safety controls

Profiles. UNIFI_PROFILE registers only one group of modules, so the client sees fewer tool definitions:

ProfileToolsCovers
network48Clients, networks, WiFi, DHCP, DNS, WAN, vouchers, channel planning
devices53Devices, control, migration, ports, switching, topology, diagnostics
security47Firewall, ZBF, ACLs, port forwarding, VPN, content filtering
system182Sites, backups, events, DPI, QoS, RADIUS, traffic flows, Protect, cloud
protect75The Protect modules
mobility / innerspace / carrier12 / 10 / 15One cloud API each
minimal19Sites, clients, devices

Counts include the four fleet tools every profile gets. An unknown profile logs a warning and loads everything.

Safety controls.

  • Every mutating tool requires confirm=True, and dry_run=True returns the change it would make without making it.
  • UNIFI_READ_ONLY=true leaves mutating tools out of the tool list entirely. UNIFI_DRY_RUN=true forces every mutating call into preview mode.
  • 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.
  • 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.
  • 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.
  • Inputs are validated with Pydantic, and credentials are redacted from logs.

Network transports and deployment

stdio is the default and needs no port. To serve MCP over the network, use Streamable HTTP:

bash
export MCP_SERVER_TRANSPORT=streamable_httpexport MCP_SERVER_PORT=3000export MCP_AUTH_TOKEN=$(openssl rand -hex 32)   # required on every network transportunifi-mcp-server# Listening on 127.0.0.1:3000; clients send Authorization: Bearer $MCP_AUTH_TOKEN

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).

Container, with the published port on loopback:

yaml
services:  unifi-mcp:    image: ghcr.io/enuno/unifi-mcp-server:latest    environment:      UNIFI_API_KEY: your-api-key      UNIFI_API_TYPE: local      UNIFI_LOCAL_HOST: 192.168.2.1      MCP_SERVER_TRANSPORT: streamable_http      MCP_SERVER_PORT: 3000      MCP_SERVER_HOST: 0.0.0.0          # inside the container only      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}    ports:      - "127.0.0.1:3000:3000"

The repository's docker-compose.yml adds Redis and the MCP Toolbox dashboard (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.

  • Ansible: deploy/ansible/ 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/.
  • Kubernetes: deploy/helm/unifi-mcp/ is a Helm chart for the server alone or in fleet mode with workers, taking every credential from an existing Secret.
  • 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.

Calling the server from code

Any MCP client library works. With the FastMCP client:

python
import asyncio
from fastmcp import Client
config = {    "mcpServers": {        "unifi": {            "command": "unifi-mcp-server",            "env": {                "UNIFI_API_KEY": "<your-api-key>",                "UNIFI_API_TYPE": "local",                "UNIFI_LOCAL_HOST": "192.168.2.1",            },        }    }}

async def main() -> None:    async with Client(config) as client:        sites = await client.call_tool("list_sites", {})        print(sites.data)
        clients = await client.call_tool("list_active_clients", {"site_id": "default"})        print(clients.data)
        # Mutations need confirm=True; dry_run=True previews the change.        preview = await client.call_tool(            "create_firewall_zone",            {"site_id": "default", "name": "IoT", "confirm": True, "dry_run": True},        )        print(preview.data)

asyncio.run(main())

bin/unifi-cli runs a single tool from a shell (unifi-cli list-clients --site default); see docs/SKILLS.md.

Native MCP prompts

Besides the tools, the server exposes eight parameterised UniFi operational workflows through the standard MCP prompts interface. A client discovers them with prompts/list and retrieves a rendered workflow brief with prompts/get.

python
import asyncio
from fastmcp import Client
config = {    "mcpServers": {        "unifi": {            "command": "unifi-mcp-server",            "env": {                "UNIFI_API_KEY": "<your-api-key>",                "UNIFI_API_TYPE": "local",                "UNIFI_LOCAL_HOST": "192.168.2.1",            },        }    }}

async def main() -> None:    async with Client(config) as client:        for prompt in await client.list_prompts():            print(prompt.name, prompt.description)
        result = await client.get_prompt(            "network_health_check",            {"site_id": "default", "focus": "wan"},        )        for message in result.messages:            print(message.content.text)

asyncio.run(main())

The prompts are network_health_check, troubleshoot_client_connectivity, troubleshoot_wifi_performance, investigate_device, review_firewall_policy, plan_network_change, protect_health_check and fleet_health_summary. A workflow is advertised only when the tools it needs are registered on this server, so the prompt list follows the API mode, the profile and the read-only and dry-run settings.

Retrieving a prompt does not run the workflow and grants no approval. The rendered text tells an agent which read tools to call and what to report; the agent calls the tools itself, and the server's role checks, confirm gate and audit trail still apply.

Use make inspect to open the MCP Inspector and browse the prompts, or the MCPJungle CLI to check what the gateway forwards:

bash
mcpjungle list prompts --server unifimcpjungle get prompt unifi__network_health_check --arg site_id=default

A tools-only client will not display the prompts; that is a client limitation. There is no prompts-as-tools shim.

See docs/PROMPTS.md for the full catalog, the availability matrix, the validation rules and the manual acceptance steps.

Documentation

DocumentContents
API.mdEvery MCP tool and resource, with parameters and examples
docs/PROMPTS.mdThe native MCP prompt catalog, with arguments and availability rules
A2A.mdThe agent card, the capability manifest and the delegation endpoint
docs/AUDIT_A2A_SKILLS.mdThe A2A and skills audit: what was implemented, what was not, and why
docs/SKILLS.mdAgent skills, profiles and the CLI wrapper
docs/UNIFI_API.mdThe UniFi endpoints behind the tools
MULTI_CONTROLLER.mdFleet mode: controllers, tokens and roles
METRICS.md, WEBHOOK_SETUP.md, A2A.mdMetrics, webhooks, the A2A agent endpoints
NETWORK_PLAYBOOK.md, HARBOR_SETUP.mdOperating runbooks
SECURITY.mdReporting vulnerabilities, audit logging and hardening
SPEC.md, DEVELOPMENT_PLAN.md, ROADMAP.mdArchitecture target and roadmap
CHANGELOG.md, docs/RELEASE_PROCESS.mdRelease history and how releases are cut and published

Development

bash
git clone https://github.com/enuno/unifi-mcp-server.gitcd unifi-mcp-servermake install    # uv sync from uv.lock with the dev extra (no activation needed)make hooks      # pre-commit and commit-msg hookscp .env.example .env   # then set UNIFI_API_KEY and, for local mode, UNIFI_LOCAL_HOST
make test       # unit testsmake ci         # every blocking CI check: lint, typecheck, security, docs coverage, tests with the 80% gatemake inspect    # open the server in the MCP Inspector (needs Node.js)make help       # list every target

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.

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 and CLAUDE.md describe the conventions in detail, and commands.md lists the development commands.

Contributing

Contributions from people and AI coding agents are welcome. See CONTRIBUTING.md and AGENTS.md.

  1. Fork the repository and create a branch.
  2. Write tests first, keep new code at 80% coverage or better, and run make ci.
  3. Use conventional commit messages (feat: ..., fix: ...) and open a pull request.

Issues with [Bug] in the title opened by a maintainer or collaborator get an automated first analysis; other reports are triaged by hand (details).

Security

Report vulnerabilities as described in SECURITY.md. Never commit credentials.

Acknowledgments

License

Apache License 2.0. See LICENSE.

Links

[Star History Chart]

來源:README.md,提交 18f0422

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.2.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分