
Unifi Mcp Server
io.github.enuno由 GitHub 账号 enuno 发布v0.2.0更新于 Nov 10, 2026
An MCP server that leverages official UniFi API
概览
将 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。
安装
在 SourceWeft 中
- 打开 控制台中的 Unifi Mcp Server,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
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
- API modes
- Quick start
- Agent skills
- Tool profiles and safety controls
- Network transports and deployment
- Calling the server from code
- Native MCP prompts
- Documentation
- Development
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/listandprompts/getoperations. See docs/PROMPTS.md. - Safety: every mutating tool needs
confirm=Trueand supportsdry_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-cardand/.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.
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
- Sign in to UniFi Site Manager.
- Go to Settings → Control Plane → Integrations and choose Create API Key.
- Copy the key. It is shown only once.
2. Install
Or use the container image (amd64, arm64 and arm/v7; the -fleet variant for amd64 and arm64):
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:
If you installed with pip, use "command": "unifi-mcp-server" and drop args. To run the container instead:
Keep -i and do not add -d: the client talks to the server over the container's stdin and stdout.
4. Main settings
.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)
Changing this codebase (developer skills)
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:
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:
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, anddry_run=Truereturns the change it would make without making it. UNIFI_READ_ONLY=trueleaves mutating tools out of the tool list entirely.UNIFI_DRY_RUN=trueforces every mutating call into preview mode.DEBUG=trueaddsdebug_api_request, a raw GET or DELETE to any controller endpoint. It is a destructive-tier tool, a DELETE needsconfirm=True, and read-only mode removes it. LeaveDEBUGunset in production.- With tokens, each tool has a risk tier (
read,write,destructive) and each role a set of tiers:viewerreads,operatorwrites, andadmincan 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:
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:
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-localormake ansible-dev-deploybuild the current working tree — including uncommitted changes — tag itlocal-<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:
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.
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:
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
Development
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.
- Fork the repository and create a branch.
- Write tests first, keep new code at 80% coverage or better, and run
make ci. - 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
- sirkirby/unifi-network-mcp, the reference implementation
- MakeWithData's UniFi MCP guide
- Model Context Protocol and FastMCP
License
Apache License 2.0. See LICENSE.
Links
- Issues and discussions: GitHub Issues, GitHub Discussions
- Releases: https://github.com/enuno/unifi-mcp-server/releases
- PyPI: https://pypi.org/project/unifi-mcp-server/
- Container images: https://ghcr.io/enuno/unifi-mcp-server
- MCP Registry: search for
io.github.enuno/unifi-mcp-serverat https://registry.modelcontextprotocol.io
来源:README.md,提交 18f0422
工具
0版本历史
1- v0.2.0最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分