UniFi MCP Server

社区

通过官方 UniFi API 管理网络设备、WiFi 与防火墙的 MCP 服务器

分类: 其他第 165 / 230
Stars: ★ 296 非常热门
传输方式: stdio（本地进程） · SSE · Streamable HTTP
运行环境: Python 3.10+ · Docker · Node.js
凭据: 需要 API Key / 凭据
许可证: Apache-2.0
最近提交: 7 天前
工具数: 5

48FMRS · D

功能覆盖面广（设备、网络、WiFi、防火墙、QoS、备份、拓扑等），但仓库中 server.json 清单与 README 所述的最新版本在包管理方式、传输与认证变量上存在明显不一致，且多项企业级安全特性仍处于规划阶段，建议使用前仔细核对实际安装版本的文档。

最强项 · 维护活跃度 15/20 最弱项 · 可靠性 6/20

可靠性

6/20

安全与权限

10/20

维护活跃度

15/20

文档质量

9/20

安装易用性

8/20

查看各项评分依据

可靠性 6/20: server.json 声明的是 npm 包（stdio 传输），环境变量为 UNIFI_HOST/UNIFI_USERNAME/UNIFI_PASSWORD/UNIFI_PORT/UNIFI_VERIFY_SSL/UNIFI_SITE；但 README 通篇描述的是通过 PyPI 安装的 Python 项目（pip install unifi-mcp-server，Python 3.10+），使用完全不同的环境变量（UNIFI_API_KEY、UNIFI_API_TYPE、UNIFI_LOCAL_HOST 等），全文未出现 UNIFI_USERNAME/PASSWORD。这是清单与实际运行时之间的根本性不一致，按清单原样安装大概率无法正常工作或无法鉴权。README 还记载了此前一次严重的启动期 ImportError（issue #42）曾导致服务完全无法启动。工具数量的说法也自相矛盾（74 个 / ~220 个 / 215+ 个），说明文档与代码存在漂移。由于仅有 README/manifest 而无法验证实际 CI 与测试文件，按静态评审上限本维度不应超过 12 分，叠加清单缺陷进一步下调。
安全与权限 10/20: README 说明所有变更类操作需要显式 confirm=True，这是一个积极的基线设计；但 dry-run、审计日志、RBAC 均被明确标注为「计划中」而非已实现，说明当前的最小权限与可审计性控制并不完整。文档给出的 .env 模板中本地网关默认 UNIFI_LOCAL_VERIFY_SSL=false，即默认关闭 TLS 证书校验，存在真实（尽管是本地网络范围内）的中间人风险，且是默认而非可选开启。凭据模型本身也存在矛盾：清单要求用户名+密码（密码标记为 secret），而 README 的整套安全/配置叙述都基于 API Key，未描述用户名密码流程，因此无法确认凭据实际如何存储与限权。未发现恶意代码、数据窃取等红线问题，故不落入 0-4 分区间，但控制不完整加上默认关闭证书校验，评分定为中低位。
维护活跃度 15/20: README 显示真实且活跃的发布节奏（0.2.0 → 0.2.5），附带带日期的变更记录、CI/安全扫描徽章、Codecov 集成、PyPI/Docker/npm 多渠道发布，以及结构化的路线图文档（DEVELOPMENT_PLAN.md、SPEC.md）。仓库采用 Apache-2.0 许可证，提供 SECURITY.md 作为漏洞报告渠道，并描述了对 issue 的自动化分诊机制。仓库未被归档，24 个未关闭 issue 处于可控范围。这些迹象表明存在真实的维护主体与流程，但由于无法直接核实提交历史，未给满分。
文档质量 9/20: 文档体量大且分层清晰（README、API.md、SPEC.md、DEVELOPMENT_PLAN.md、SECURITY.md、docs/ 子目录、skills/），涵盖安装、传输方式、API 模式与故障排查手册。但内部存在实质性自相矛盾，削弱可信度：工具数量表述不一致（74 个 / 「约220个异步工具函数」/ 「215+ 个已注册工具」，以及项目结构中「213个测试，37%覆盖率」与正文「1,236 个测试通过」相冲突）；更关键的是，文档中的环境变量与包注册方式（PyPI/Python）与 server 清单（npm/用户名密码）完全不符。这不是拼写错误，而是核心配置事实层面的冲突，按证据规则应视为文档质量的实质缺陷，而非仅凭篇幅给高分。
安装易用性 8/20: README 提供了多种安装路径（PyPI pip/uv、Docker、Docker Compose、源码构建），并给出了 Claude Desktop / Cursor 的具体客户端配置 JSON，这是良好实践。但按静态评审校准，若无可验证的执行证据本维度不应超过 15 分；且本次审查对象 server.json 清单（npm 包、stdio、UNIFI_HOST/USERNAME/PASSWORD）与 README 实际的安装/配置指引（PyPI、UNIFI_API_KEY、UNIFI_LOCAL_HOST）相互矛盾——按清单字面操作的用户很可能无法完成连接或鉴权。这种审查对象自身清单与其配套 README 之间的核心不一致，是实际部署中的重大风险点。

静态评测 · 未实际运行收录于 2026-08-26

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络修改第三方账户数据

适合谁

自建 UniFi 本地网关且愿意通过 AI 代理做网络运维的家庭/小型办公用户
熟悉 UniFi 控制器概念、愿意逐步验证 MCP 工具行为的技术用户

不适合谁

只能通过云 API 访问、需要完整设备/客户端级控制的用户（云模式功能受限，只读为主）
要求生产级审计日志、RBAC、试运行模式等安全护栏已完全落地的企业场景（这些据 README 仍在规划中）

所需权限

UniFi 控制器地址（本地网关 IP 或云 API）及登录凭证（用户名/密码或 API Key）
对网络的直接访问权限（本地网关模式需要局域网可达）
若使用会修改配置的工具，还需要对防火墙规则、网络/VLAN、WiFi、设备状态的写权限

风险与副作用

该服务器可对网络基础设施进行较大范围的管理操作（重启/升级设备、修改防火墙与 WiFi），配置错误可能导致网络中断
凭证（API Key 或用户名/密码）以环境变量明文形式配置，需妥善保管
README 显示本地网关模式默认关闭 SSL 证书校验（UNIFI_LOCAL_VERIFY_SSL 默认为 false），存在中间人风险
server.json 清单与 README 所述的版本、包管理方式、认证变量并不一致，直接照抄任一方配置都可能无法连接
试运行模式、审计日志、基于角色的访问控制等安全特性据 README 仍标注为“规划中”，尚不能依赖其提供的额外防护

安装接入

准备工作

运行环境：Python 3.10+ · Docker · Node.js

UNIFI_HOST 必填 UniFi 控制器的主机名或 IP 地址（server. 清单要求）。

UNIFI_USERNAME 必填 UniFi 控制器用户名。

UNIFI_PASSWORD 必填密钥 UniFi 控制器密码，属敏感信息。

UNIFI_API_KEY 必填密钥在 unifi.ui.com 的 Settings → Control Plane → Integrations 中创建的 API 密钥，只显示一次。

UNIFI_API_TYPE 必填 API 模式：local（推荐）、cloud-ea 或 cloud-v1。

REDIS_PASSWORD 可选密钥 Redis 密码（如需要认证），属敏感信息。

WEBHOOK_SECRET 可选密钥 Webhook HMAC 签名验证密钥，属敏感信息。

其他可选配置项（16 个）

UNIFI_PORT 可选控制器端口，默认 443。

UNIFI_VERIFY_SSL 可选是否校验 SSL 证书，默认 true。

UNIFI_SITE 可选 UniFi 站点名称，默认 default。

UNIFI_LOCAL_HOST 可选本地网关 IP，例如 192.168.2.1，local 模式使用。

UNIFI_LOCAL_PORT 可选本地网关端口，默认 443。

UNIFI_LOCAL_VERIFY_SSL 可选是否校验本地网关 SSL 证书，默认 false。

UNIFI_CLOUD_API_URL 可选云 API 地址，默认 https://api.ui.com。

UNIFI_DEFAULT_SITE 可选默认站点 ID，默认 default。

UNIFI_SITE_MANAGER_ENABLED 可选启用 Site Manager 多站点工具（仅 cloud-ea），默认 false。

UNIFI_PROFILE 可选工具暴露配置：network、devices、security、system 或 minimal，默认加载全部工具。

MCP_SERVER_TRANSPORT 可选传输模式：stdio（默认）、sse、http 或 streamable_http。

MCP_SERVER_HOST 可选 HTTP/SSE 模式绑定地址，默认 0.0.0.0。

MCP_SERVER_PORT 可选 HTTP/SSE 模式端口，默认 3000。

REDIS_HOST 可选可选 Redis 缓存主机，默认 localhost。

REDIS_PORT 可选可选 Redis 缓存端口，默认 6379。

REDIS_DB 可选可选 Redis 数据库编号，默认 0。

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"}}}}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "unifi": {
      "command": "npx",
      "args": [
        "-y",
        "unifi-mcp-server"
      ],
      "env": {
        "UNIFI_HOST": "your-unifi-controller-host",
        "UNIFI_USERNAME": "your-username",
        "UNIFI_PASSWORD": "your-password"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add unifi -e UNIFI_HOST=your-unifi-controller-host -e UNIFI_USERNAME=your-username -e UNIFI_PASSWORD=your-password -- npx -y unifi-mcp-server

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

启动服务器后，检查 MCP 客户端工具列表中是否出现 list_devices 等工具，然后请求列出站点设备以确认连接正常。

常见排障

先确认已安装的具体版本/来源（npm 清单 vs PyPI README），核对对应的环境变量名称是否匹配
确认 UNIFI_API_TYPE（local/cloud-ea/cloud-v1，如适用）与实际网络可达性一致；云模式无法访问单个设备/客户端
执行修改类工具前检查是否传入了必需的 confirm 参数
本地网关连接失败时检查证书校验设置（VERIFY_SSL）与网关 IP/端口是否正确
若使用 SSE/HTTP 等网络传输模式，确认 MCP_SERVER_PORT 未被占用且客户端 URL 配置正确

试试这样问

连接成功后，可以直接对 AI 助手这样说：

列出我默认站点上的所有 UniFi 设备
创建一个名为 Guest WiFi、带 VLAN 隔离的访客 WiFi 网络（已确认）
显示过去 24 小时内流量最高的前 5 个应用程序
创建一个 IoT 防火墙区域，并设置策略允许 LAN 访问 IoT

工具能力 5

list_devices 只读

列出指定站点下的 UniFi 设备（接入点、交换机、网关）及其状态。

create_wlan 写入

创建新的 WiFi/SSID 网络，可配置加密方式、访客网络与 VLAN 隔离。

list_top_applications 只读

基于深度包检测（DPI）统计，获取带宽消耗最高的应用列表。

create_firewall_zone 写入

创建基于区域的防火墙（ZBF）区域，用于网络分段。

update_zbf_policy 写入

更新区域间防火墙策略（例如允许或拒绝两个区域之间的流量）。

使用场景

让 AI 助手查询 UniFi 设备、客户端与网络状态

通过对话创建/调整 WiFi 网络、VLAN 与防火墙策略

获取带宽 Top 应用等 DPI 统计用于网络排障

在多站点环境下做跨站点汇总分析（云 API 模式下功能受限）

支持客户端

Claude Desktop

Cursor

依据项目文档列出，未经本站实测。

详细介绍

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）仍处于规划中、尚未实现，使用前应以实际安装版本的文档为准。