unifi

UniFi MCP 服务

面向 MSP 的 UniFi MCP——基于官方 Site Manager API 和 Cloud Connector 构建，提供其他 UniFi MCP 都不具备的跨站点分析功能。

共 54 个工具，分为 7 个语义分析聚合工具、9 个原始 Site Manager 工具和 35 个 Cloud Connector 工具；另有 2 个可选的本地控制器工具，可提供 Cloud API 未公开的端口错误计数器和 SFP DDM 数据。基于精心设定的阈值给出严重程度判定（healthy/info/warning/critical）。提供 8 个 MCP 提示词（4 个全网运维 + 4 个 MSP 工作流）。仅支持只读——Ubiquiti 的 API 密钥尚不支持写入操作。

启动前诊断

npx -y @us-all/unifi-mcp --doctor

启动前验证环境变量、连接 Site Manager API、探测 Cloud Connector（如果设置了所有者密钥），并检查类别开关。遇到严重问题时以非零状态码退出，因此可用于 CI / 部署前脚本。

它的独特之处

• Site Manager 分析——site-health-timeline、summarize-site、firmware-inventory、compare-sites、wan-uptime-trend、top-clients-by-bandwidth、list-sites-overview。其他 UniFi MCP 都不提供这些功能。
• 严重程度判定，而非仅提供数字——每个分析工具都会返回 healthy / info / warning / critical / unknown，并附上精心整理的原因说明。阈值经过精心设定（例如 WAN 运行时间 <90% = critical，重启后 startupTime <1h = critical）。
• 一流的 Cloud Connector 支持——通过官方 /v1/connector/consoles/{id}/... 代理提供 35 个工具。区分 connectorAvailable（功能可用性）和 connectorResolved（本次调用状态）。
• 聚合工具——将 3–7 次顺序调用整合为 1 次，并通过 caveats 数组指出部分失败（例如，Site Manager API 无法按时间窗口筛选 WAN 运行时间，此限制会明确显示）。
• MCP 提示词（8 个）——全网运维：triage-site-degradation、firmware-rollout-audit、wan-uptime-report、cross-site-anomaly-detection。MSP 工作流：msp-onboard-site-checklist、msp-monthly-client-report、msp-fleet-firmware-plan、msp-bandwidth-complaint-investigation。
• 专为节省 Token 而设计——在所有 @us-all/* MCP 中，Schema 占用最小（设置所有者密钥时默认约 5K Token）。可在单个会话中分析包含 200 多台设备的全网。
• Apps SDK 卡片——在 ChatGPT 客户端中，summarize-site 会通过 _meta["openai/outputTemplate"] 渲染为全网状态卡片（在线率、WAN 运行时间、网关、设备）。Claude 客户端则会收到相同的 JSON 内容。
• stdio + Streamable HTTP——默认使用 stdio。设置 MCP_TRANSPORT=http 可用于 ChatGPT Apps SDK 或远程客户端（通过 MCP_HTTP_TOKEN 使用 Bearer 身份验证）。
• 直接访问本地控制器（v1.13.0）——选择启用 UNIFI_LOCAL_* 环境变量后，可启用 2 个工具，绕过 Cloud Connector，直接在局域网上访问控制器的旧版 /api/s/{site}/stat/device/{mac}：get-port-errors（端口级 rx/tx 错误、链路抖动计数器、SFP DDM——Rx/Tx 功率 dBm、温度、电压、TX/RX 故障）和 list-port-flap-summary（全网端口不稳定性排名）。提供 Integration API 未公开的数据。需要能够从局域网访问控制器。

试试这些 — 5 个提示词

将服务连接到 Claude Desktop 或 Claude Code，然后粘贴以下任意提示词：

1. MSP 晨间检查 — “检查我所有 UniFi 站点的设备群状态。标出所有状态不是 healthy 的项目，并说明严重程度和排名前 3 的问题。”
2. 固件更新审计 — “找出所有站点中固件过时的设备。按站点分组，列出当前版本与最新版本，并按重要程度排序。”
3. 站点性能下降排查 — “USM 站点有 WiFi 投诉。调取过去 24 小时的数据：设备状态、WAN 正常运行时间、近期重启记录、带宽使用量最高的客户端。是否存在异常？”
4. WAN SLA 报告 — “生成所有站点的月度 WAN 正常运行时间报告。列出超过 5 分钟的中断、双 WAN 故障转移事件，以及未达到 99.5% 目标的站点。”
5. 跨站点异常分析 — “将 USS 与我的其他站点进行比较：每个 AP 的客户端数量、流量模式、设备固件分布。标出异常值并推测最可能的原因。”
6. 端口抖动排查 (需要 UNIFI_LOCAL_*) — “按不稳定性评分排列所有交换机的端口。对排名最靠前的 3 个问题端口，如果存在 SFP DDM 数据，则调取并判断是信号本身不佳还是下游出现问题。”

何时使用此 MCP，而非其他 UniFi MCP

	sirkirby/unifi-mcp	enuno/unifi-mcp-server	@us-all/unifi-mcp（本项目）
GitHub 星标数	291	117	—
工具数量	224	74	54
覆盖范围	网络 + Protect + Access + Drive	网络 + 多站点 + QoS + 备份	Site Manager + Cloud Connector + 分析
Site Manager API	❌	部分支持	✅ 深度支持 + 分析
Cloud Connector	❌	部分支持（3 种模式）	✅ 区分可用与已解析数据
UniFi Protect（摄像头）	✅	❌	❌（不在覆盖范围内）
UniFi Access（门禁）	✅	❌	❌（不在覆盖范围内）
聚合工具	❌	❌	✅ 7 个
严重程度判定	❌	❌	✅ 精选阈值
MCP 提示词	❌	❌	✅ 8 个（含 4 个 MSP 工作流）

需要摄像头（Protect）或门禁时，使用 sirkirby。如果需要广泛访问原始 Network API，请使用 enuno。如果需要 MSP 风格的多站点分析、设备群排查，以及针对多个控制台提出“是否有异常？”这类问题，请使用本服务。

安装

Claude Desktop

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "@us-all/unifi-mcp"],
      "env": {
        "UNIFI_API_KEY": "<your-key>",
        "UNIFI_API_KEY_OWNER": "<owner-key-or-same-key-if-role=owner>"
      }
    }
  }
}

Claude Code

claude mcp add unifi -s user \
  -e UNIFI_API_KEY=<your-key> \
  -e UNIFI_API_KEY_OWNER=<owner-key> \
  -- npx -y @us-all/unifi-mcp

从源代码构建

git clone https://github.com/us-all/unifi-mcp-server.git
cd unifi-mcp-server && pnpm install && pnpm build
node dist/index.js

API 密钥 — 选择哪种，以及在哪里获取

这是最常见的入门障碍。UniFi 通过相同的 https://api.ui.com/v1 提供两个接口：

接口	提供内容	路径	环境变量
Site Manager	主机、站点、设备摘要、ISP 指标、SD-WAN 配置（聚合数据，覆盖整个控制台）	/v1/hosts、/v1/sites、/v1/devices、/v1/sd-wan-configs	UNIFI_API_KEY
Cloud Connector	单台设备、单个客户端、网络、防火墙、WiFi（代理到本地控制器）	/v1/connector/consoles/{hostId}/...	UNIFI_API_KEY_OWNER

API 密钥的权限继承自创建密钥的账户角色。

账户角色	Site Manager	Cloud Connector
管理员（非所有者）	✅	❌ 403
所有者	✅	✅

如果你拥有所有者角色，请将两个环境变量设为相同的密钥。 对于 @us-all 操作人员来说，这是最常见的情况。

获取密钥：unifi.ui.com → Settings → API → Generate。目前 GA 中唯一可用的选项是 View Only（Full Access 为灰色，写入权限需要加入 Early Access 计划）。

Cloud Connector 要求

• 控制台固件 ≥ 5.0.3
• API 路径：https://api.ui.com/v1/connector/consoles/{hostId}/{appPath}
• 本地 siteId 是 UUID，而不是字面字符串 default
• 可用端点：Network integration API（/network/integration/v1/sites、devices、clients、networks）。旧版路径（/api/s/{site}/stat/event）会返回 404。未公开事件日志 / syslog。

本地控制器（可选，v1.13.0+）

新增 2 个工具，填补 Cloud Connector 未涵盖的功能：每端口错误计数、链路抖动计数和 SFP DDM。这些数据位于 /api/s/{site}/stat/device/{mac}（旧版 API）中，官方 Network Integration API 并未公开这些数据（已根据 OpenAPI 规范 v10.4.57 验证）。

要求：

• 运行此 MCP 的主机可通过 LAN/VPN 访问控制器（通常为 https://<controller-ip>）
• 控制器的本地账户（Viewer / Limited Admin 角色即可，无需 Owner 凭据）
• 自签名证书处理：对于原版 UDM Pro，设置 UNIFI_LOCAL_INSECURE=true

身份验证流程：POST /api/auth/login（Cookie）→ 后续所有调用都会复用此会话，遇到 401 时自动重新登录。只读。

配置

变量	必需	默认值	描述
UNIFI_API_KEY	✅	—	来自 unifi.ui.com 的 API 密钥（任意管理员角色）
UNIFI_API_KEY_OWNER	❌	—	Owner 角色的 API 密钥——启用 35 个 Cloud Connector 工具。如果你的密钥具有 Owner 角色，请将此项设为相同的值。
UNIFI_API_URL	❌	https://api.ui.com/v1	API 基础 URL
UNIFI_TOOLS	❌	—	以逗号分隔的类别允许列表。
UNIFI_DISABLE	❌	—	以逗号分隔的类别拒绝列表。设置 UNIFI_TOOLS 时会忽略此项。
MCP_TRANSPORT	❌	stdio	设为 http 以启用 Streamable HTTP 传输
MCP_HTTP_TOKEN	条件必需	—	Bearer 令牌。MCP_TRANSPORT=http 时必需
MCP_HTTP_PORT	❌	3000	HTTP 监听端口
MCP_HTTP_HOST	❌	127.0.0.1	HTTP 绑定主机（本地主机自动启用 DNS 重绑定保护）
MCP_HTTP_SKIP_AUTH	❌	false	跳过 Bearer 身份验证——例如，部署在负责处理身份验证的反向代理之后时
UNIFI_LOCAL_URL	❌	—	本地控制器 URL（例如 https://10.10.1.1）。设置此项及 USER/PASS 后，可启用 2 个 local 类别工具。
UNIFI_LOCAL_USER	条件必需	—	控制器本地账户用户名（设置 UNIFI_LOCAL_URL 时必需）。Viewer/Limited Admin 角色即可。
UNIFI_LOCAL_PASS	条件必需	—	控制器本地账户密码（设置 UNIFI_LOCAL_URL 时必需）。
UNIFI_LOCAL_SITE	❌	default	旧版 /api/s/{site}/* 的站点标识。
UNIFI_LOCAL_INSECURE	❌	false	接受自签名证书（UDM Pro 通常需要）。

类别（9 个）：analysis、raw、devices、clients、networks、firewall、wan、reference、local。

当 MCP_TRANSPORT=http 时：POST /mcp（使用 Bearer 身份验证的 JSON-RPC）+ GET /health（公开的存活状态检查）。

令牌效率

在所有 @us-all/* MCP 中，架构占用最小。

场景	工具数	架构令牌数
默认，不含 Owner	17	1,700
UNIFI_TOOLS=analysis	8	1,000（−42%）
默认，含 Owner 密钥	52	~5,000
UNIFI_TOOLS=analysis + Owner	8	1,000（−80%）

严重程度与阈值

每个分析工具都会返回以下其中一种状态：

• healthy — 无问题
• info — 信息提示，无需操作
• warning — 需要关注
• critical — 需要立即处理
• unknown — API 故障或数据不完整

精选阈值：

条件	严重程度
设备离线	critical
startupTime < 1h	critical（刚重启）
startupTime < 24h	warning（近期重启）
startupTime < 72h	info（监控）
WAN 正常运行时间 < 90%	critical
WAN 正常运行时间 < 95%	warning

MCP 提示词（8 个）

可通过 MCP prompts/list 使用的工作流模板。其中 4 个用于车队运维，另 4 个为 MSP 专用（托管服务提供商工作流）。

车队运维：

• triage-site-degradation — 站点投诉工作流：依次检查设备、WAN、重启情况和客户端。
• firmware-rollout-audit — 全车队固件差异与部署安全检查。
• wan-uptime-report — 跨站点的月度 WAN SLA 风格报告。
• cross-site-anomaly-detection — 将站点与车队基线比较，并标记异常值。

MSP 工作流：

• msp-onboard-site-checklist — 新增客户站点的通过/未通过就绪检查清单（固件最低版本、控制台连通性、运行时间趋势、连接器可用性、防火墙状态、近期重启、待处理设备）。
• msp-monthly-client-report — 面向客户的月度健康报告（单个站点 → 概览、网络可用性、设备、热门用户、建议），采用非技术性措辞。
• msp-fleet-firmware-plan — 分阶段的 N 波部署计划，将固件升级到目标版本，按风险承受能力排序，并包含维护时段和回滚触发条件。
• msp-bandwidth-complaint-investigation — 通过 WAN 趋势、ISP 指标、热门客户端、DPI 类别和近期重启情况，分诊“X 站点的互联网很慢”问题。

MCP 资源

• unifi://site/{hostName}/devices — 站点设备快照
• unifi://reboots/recent — 全车队近期重启的设备

工具（54 个 + 2 个可选本地工具）

共 9 个类别。使用 search-tools 在运行时发现工具；完整列表已在下方折叠。仅当设置了 UNIFI_API_KEY_OWNER 时才会注册 Cloud Connector 工具（33 个）；未设置时仅提供 19 个工具。仅当设置了 UNIFI_LOCAL_URL/USER/PASS 时才会注册本地控制器工具（2 个）。

分组	工具数
语义分析（含聚合）	9
Site Manager 原始工具	9
Cloud Connector（设备/客户端/网络/WiFi/防火墙/WAN/参考）	33
本地站点（list-local-sites、get-app-info）	2
本地控制器（get-port-errors、list-port-flap-summary）	2
元工具（search-tools）	1

完整工具列表

语义分析（9 个）

list-sites-overview、analyze-site-health、detect-recent-reboots、compare-sites、firmware-inventory、wan-uptime-trend、top-clients-by-bandwidth、summarize-site （聚合）、site-health-timeline （聚合）

Site Manager API（9 个）

list-hosts、get-host、list-sites、list-devices、get-isp-metrics（可选）、query-isp-metrics（可选）、list-sdwan-configs、get-sdwan-config、get-sdwan-config-status

Cloud Connector — 设备（4 个）

get-device-details、get-device-by-id、get-device-statistics、list-pending-devices

Cloud Connector — 客户端（2 个）

list-site-clients、get-client-details

Cloud Connector — 网络（3 个）

list-networks、get-network-details、get-network-references

Cloud Connector — WiFi（2 个）

list-wifi-broadcasts、get-wifi-broadcast-details

Cloud Connector — 防火墙 / ACL / DNS（10 个）

list-firewall-zones、get-firewall-zone、list-firewall-policies、get-firewall-policy、get-firewall-policy-ordering、list-acl-rules、get-acl-rule、get-acl-rule-ordering、list-dns-policies、get-dns-policy

Cloud Connector — 流量 / WAN / VPN（5 个）

list-traffic-matching-lists、get-traffic-matching-list、list-wans、list-vpn-tunnels、list-vpn-servers

Cloud Connector — 热点 / 参考（7 个）

list-vouchers、get-voucher-details、list-radius-profiles、list-device-tags、list-dpi-categories、list-dpi-applications、list-countries

本地站点（2 个）

list-local-sites、get-app-info

### 本地控制器（2 个，通过 `UNIFI_LOCAL_*` 选择启用） - `get-port-errors` — 每个端口的 `rx_errors` / `tx_errors` / `rx_dropped` / `tx_dropped` 和链路状态，以及持久化的链路抖动计数器（`linkDownCount`、`stpChangeCount`、`anomalies`）；检测到收发器时，还会提供 **SFP DDM** 数据（`rxPowerDbm`、`txPowerDbm`、`temperatureC`、`voltageV`、`txBiasMa`、`rxFault`、`txFault`、厂商/部件/序列号）。支持使用 `onlyProblems` 筛选问题，以便分诊。 - `list-port-flap-summary` — 遍历控制器中的所有交换机，按评分 `linkDownCount*2 + stpChangeCount + rx_errors + tx_errors` 对整个设备群的端口排序。一次性显示站点中各处不稳定的线缆、收发器和 NIC 省电端点。计数器会在查询之间持久保留（仅在交换机重启时重置）。

元数据

search-tools — 按关键字查询其他工具；始终启用。

架构

Claude → MCP stdio → src/index.ts
                      ├── tools/analysis.ts     → Site Manager API (UNIFI_API_KEY)
                      ├── tools/*.ts (raw)       → Site Manager API (UNIFI_API_KEY)
                      ├── tools/connector.ts     → Cloud Connector  (UNIFI_API_KEY_OWNER)
                      └── tools/local-ports.ts   → Local Controller (UNIFI_LOCAL_URL + LAN)
                      helpers/resolver.ts        → hostName ↔ ID mapping

基于 @us-all/mcp-toolkit 构建：

• extractFields — 节省令牌的响应投影
• aggregate(fetchers, caveats) — 为 summarize-site / site-health-timeline 提供扇出辅助功能
• createWrapToolHandler — X-API-KEY 脱敏和 ConnectorError/UniFiError 提取
• 重试：最多 3 次，采用指数退避（1s → 2s → 4s）并加入抖动；Cloud Connector 超时为 30s

限制

• 只读 — UniFi API 密钥目前不支持写入（GA 版中的 Full Access 角色为灰色禁用状态）。
• 速率限制 — 稳定版 v1 为 10,000 次请求/分钟；Early Access 为 100 次请求/分钟。
• Cloud Connector 部分代理 — Network 集成 API 可用；旧版路径返回 404；不提供事件日志/系统日志。
• ISP Metrics — 根据账户/套餐不同，可能返回 404。

技术栈

Node.js 22+ • TypeScript strict ESM • pnpm • @modelcontextprotocol/sdk • zod v4 • dotenv。

许可证

MIT