适合谁
- 自建 UniFi 本地网关且愿意通过 AI 代理做网络运维的家庭/小型办公用户
- 熟悉 UniFi 控制器概念、愿意逐步验证 MCP 工具行为的技术用户
U
48FMRS · D
功能覆盖面广（设备、网络、WiFi、防火墙、QoS、备份、拓扑等），但仓库中 server.json 清单与 README 所述的最新版本在包管理方式、传输与认证变量上存在明显不一致，且多项企业级安全特性仍处于规划阶段，建议使用前仔细核对实际安装版本的文档。
UniFi MCP Server 是一个第三方社区项目（作者 enuno），通过 Model Context Protocol 把 UniFi Network 控制器的官方 API 暴露给 AI 代理。它可以列出并控制设备（AP、交换机、网关）、管理客户端、创建/修改 WiFi 网络与 VLAN、配置防火墙规则与基于区域的防火墙（ZBF）、管理 QoS、备份与多站点。仓库存在两套配置说明并存的情况：随包发布的 server.json 清单（npm 包 v0.2.0，stdio 传输，使用 UNIFI_HOST/UNIFI_USERNAME/UNIFI_PASSWORD 认证）与 README 描述的最新发行版（PyPI 包 v0.2.5，使用 UNIFI_API_KEY 与 UNIFI_API_TYPE 认证，并支持 stdio/SSE/HTTP/Streamable HTTP 等多种传输）。README 还声明许多“阶段五”能力（试运行模式、审计日志、RBAC、A2A）仍处于规划中、尚未实现，使用前应以实际安装版本的文档为准。
工具能力
list_devices
列出指定站点下的 UniFi 设备（接入点、交换机、网关）及其状态。
create_wlan
创建新的 WiFi/SSID 网络，可配置加密方式、访客网络与 VLAN 隔离。
list_top_applications
基于深度包检测（DPI）统计，获取带宽消耗最高的应用列表。
create_firewall_zone
创建基于区域的防火墙（ZBF）区域，用于网络分段。
update_zbf_policy
更新区域间防火墙策略（例如允许或拒绝两个区域之间的流量）。
安装接入
1) 确认你要安装的实际发行渠道：仓库的 server.json 清单对应 npm 包（v0.2.0，stdio 传输，需要 UNIFI_HOST/UNIFI_USERNAME/UNIFI_PASSWORD），而 README 描述的最新稳定版（v0.2.5）是通过 pip install unifi-mcp-server 安装、使用 UNIFI_API_KEY 与 UNIFI_API_TYPE 认证的不同配置体系；两者环境变量不兼容，务必先确认已安装版本对应哪一套。2) 若使用 npm 包，在 MCP 客户端配置中以 npx -y unifi-mcp-server 启动，并设置 UNIFI_HOST、UNIFI_USERNAME、UNIFI_PASSWORD（可选 UNIFI_PORT、UNIFI_VERIFY_SSL、UNIFI_SITE）。3) 若使用 PyPI 包，改用 README 中给出的 UNIFI_API_KEY/UNIFI_API_TYPE/UNIFI_LOCAL_HOST 等变量。4) 重启客户端使配置生效，并先在只读工具上测试连接。
claude_desktop_config.json
{"mcpServers":{"unifi":{"command":"npx","args":["-y","unifi-mcp-server"],"env":{"UNIFI_HOST":"your-unifi-controller-host","UNIFI_USERNAME":"your-username","UNIFI_PASSWORD":"your-password"}}}}
选型与风险
不适合谁
- 只能通过云 API 访问、需要完整设备/客户端级控制的用户（云模式功能受限，只读为主）
- 要求生产级审计日志、RBAC、试运行模式等安全护栏已完全落地的企业场景（这些据 README 仍在规划中）
所需权限
- UniFi 控制器地址（本地网关 IP 或云 API）及登录凭证（用户名/密码或 API Key）
- 对网络的直接访问权限（本地网关模式需要局域网可达）
- 若使用会修改配置的工具，还需要对防火墙规则、网络/VLAN、WiFi、设备状态的写权限
风险与副作用
- 该服务器可对网络基础设施进行较大范围的管理操作（重启/升级设备、修改防火墙与 WiFi），配置错误可能导致网络中断
- 凭证（API Key 或用户名/密码）以环境变量明文形式配置，需妥善保管
- README 显示本地网关模式默认关闭 SSL 证书校验（UNIFI_LOCAL_VERIFY_SSL 默认为 false），存在中间人风险
- server.json 清单与 README 所述的版本、包管理方式、认证变量并不一致，直接照抄任一方配置都可能无法连接
- 试运行模式、审计日志、基于角色的访问控制等安全特性据 README 仍标注为“规划中”，尚不能依赖其提供的额外防护
常见排障
- 先确认已安装的具体版本/来源（npm 清单 vs PyPI README），核对对应的环境变量名称是否匹配
- 确认 UNIFI_API_TYPE（local/cloud-ea/cloud-v1，如适用）与实际网络可达性一致；云模式无法访问单个设备/客户端
- 执行修改类工具前检查是否传入了必需的 confirm 参数
- 本地网关连接失败时检查证书校验设置（VERIFY_SSL）与网关 IP/端口是否正确
- 若使用 SSE/HTTP 等网络传输模式，确认 MCP_SERVER_PORT 未被占用且客户端 URL 配置正确
使用场景
让 AI 助手查询 UniFi 设备、客户端与网络状态
通过对话创建/调整 WiFi 网络、VLAN 与防火墙策略
获取带宽 Top 应用等 DPI 统计用于网络排障
在多站点环境下做跨站点汇总分析（云 API 模式下功能受限）
支持客户端
Claude Desktop完整支持
Cursor完整支持