unifi-mcp-server

# UniFi MCP 服务器 > **MSP 风格的 UniFi MCP — 围绕官方站点管理器 API + 云连接器构建，具有跨站点分析功能，其他 UniFi MCP 不具备。** > > 54 种工具分为 7 种语义分析聚合、9 种原始站点管理器和 35 种云连接器 — 以及 2 种可选的**本地控制器**工具，用于显示每端口错误计数器和 SFP DDM，云 API 不提供这些功能。具有精选阈值的严重性判决（`healthy`/`info`/`warning`/`critical`）。8 个 MCP 提示（4 个全fleet 操作 + 4 个 MSP 工作流程）。只读 — 优比特的 API 密钥目前不支持写入。 [](https://www.npmjs.com/package/@us-all/unifi-mcp) [](https://www.npmjs.com/package/@us-all/unifi-mcp) [](#tools) [](https://github.com/us-all/mcp-toolkit/blob/main/STANDARD.md) [](https://glama.ai/mcp/servers/us-all/unifi-mcp-server) ## 预飞行诊断 ```bash npx -y @us-all/unifi-mcp --doctor ``` 验证环境变量，ping 站点管理器 API，探测云连接器（如果设置了所有者密钥），并在启动前检查类别切换。如果存在关键问题，则退出非零，以便在 CI / 预部署脚本中使用。 ## 其他 UniFi MCP 不具备的功能 - **站点管理器分析** — `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`，启动时间 <1h = `critical` 重启后）。 - **云连接器优先** — 官方 `/v1/connector/consoles/{id}/...` 代理的 35 种工具。`connectorAvailable`（能力）与 `connectorResolved`（此调用）分离。 - **聚合工具** — 将 3-7 个顺序调用折叠成 1 个，并带有 `caveats` 数组显示部分失败（例如，站点管理器 API 无法绑定 WAN 正常运行时间 — 明确显示）。 - **MCP 提示**（8）— fleet 操作：`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`。 - **设计高效使用令牌** — 所有 `@us-all/*` MCP 中最小的模式占用量（默认 ~5K 令牌，带有所有者密钥）。200 多台设备的舰队可以在单个会话内分析。 - **应用 SDK 卡片** — `summarize-site` 在 ChatGPT 客户端上呈现为舰队状态卡片（在线 %、WAN 正常运行时间、网关、设备）通过 `_meta["openai/outputTemplate"]`。Claude 客户端接收相同的 JSON 内容。 - **stdio + 流式 HTTP** — 默认使用 stdio。设置 `MCP_TRANSPORT=http` 以适用于 ChatGPT 应用 SDK 或远程客户端（通过 `MCP_HTTP_TOKEN` 进行 Bearer 身份验证）。 - **本地控制器直接访问**（v1.13.0）— 选择加入 `UNIFI_LOCAL_*` 环境变量启用 2 个工具，绕过云连接器，直接访问控制器的旧 `/api/s/{site}/stat/device/{mac}`：`get-port-errors`（每端口 rx/tx 错误、链路波动计数器、**SFP DDM** — Rx/Tx 功率 dBm、温度、电压、TX/RX 故障）和 `list-port-flap-summary`（全fleet 端口不稳定排名）。显示集成 API 不提供的功能。需要 LAN 可达性。 ## 试用 — 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（如果存在）并告诉我信号是否不良还是下游有问题。"* ## 何时使用此服务器与其他 UniFi MCP | | sirkirby/unifi-mcp | enuno/unifi-mcp-server | `@us-all/unifi-mcp`（此服务器） | |--|---|---|---| | GitHub 星级 | 291 | 117 | — | | 工具数量 | 224 | 74 | **54** | | 范围 | 网络 + Protect + Access + Drive | 网络 + 多站点 + QoS + 备份 | 站点管理器 + 云连接器 + 分析 | | 站点管理器 API | ❌ | 部分 | ✅ 深入 + 分析 | | 云连接器 | ❌ | 部分（3 种模式） | ✅ 可用/已解析分离 | | UniFi Protect（摄像头） | ✅ | ❌ | ❌（超出范围） | | UniFi Access（门） | ✅ | ❌ | ❌（超出范围） | | 聚合工具 | ❌ | ❌ | ✅ 7 | | 严重性判决 | ❌ | ❌ | ✅ 精选阈值 | | MCP 提示 | ❌ | ❌ | ✅ 8（包括 4 个 MSP 工作流程） | 在需要摄像头（Protect）或门禁（Access）时使用 **sirkirby**。在需要原始网络 API 广度时使用 **enuno**。在需要 MSP 样式的多站点分析、舰队分类和“是否有问题？”问题时使用 **此服务器**。 ## 安装 ### Claude Desktop ```json { "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 ```bash 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 ``` ### 从源码构建 ```bash git clone https://github.com/us-all/unifi-mcp-server.git cd unifi-mcp-server && pnpm install && pnpm build node dist/index.js ``` ## API 密钥 — 哪一个以及在哪里 最常见的 onboarding 摩擦。UniFi 有 **两个表面** 通过相同的 `https://api.ui.com/v1`: | 表面 | 提供什么 | 路径 | 环境变量 | |---|---|---|---| | **站点管理器** | 主机、站点、设备摘要、ISP 指标、SD-WAN 配置（聚合，控制台范围） | `/v1/hosts`、`/v1/sites`、`/v1/devices`、`/v1/sd-wan-configs` | `UNIFI_API_KEY` | | **云连接器** | 每设备、每客户端、网络、防火墙、WiFi（代理到本地控制器） | `/v1/connector/consoles/{hostId}/...` | `UNIFI_API_KEY_OWNER` | API 密钥权限从创建它们的帐户角色继承。 | 帐户角色 | 站点管理器 | 云连接器 | |---|---|---| | 管理员（非所有者） | ✅ | ❌ 403 | | **所有者** | ✅ | ✅ | **如果您拥有所有者角色，请将两个环境变量设置为相同的密钥。** 这是 `@us-all` 操作员最常见的情况。 从 [unifi.ui.com](https://unifi.ui.com) 获取密钥：设置 → API → 生成。**查看仅限** 是 GA 中唯一的选项（完整访问权限灰显 — 需要早期访问计划才能写入）。 ### 云连接器要求 - 控制台固件 ≥ 5.0.3 - API 路径：`https://api.ui.com/v1/connector/consoles/{hostId}/{appPath}` - 本地 `siteId` 是 UUID，而不是字符串 `default` - 可用端点：网络集成 API (`/network/integration/v1/sites`、设备、客户端、网络）。旧路径 (`/api/s/{site}/stat/event`) 返回 404。事件日志/系统日志未公开。 ### 本地控制器（可选，v1.13.0+） 添加 2 个工具来填充云连接器留下的空白 — 每端口错误计数器、波动计数器和 SFP DDM。这些位于 `/api/s/{site}/stat/device/{mac}`（旧版）和官方网络集成 API 不提供它们（针对 OpenAPI 规范 v10.4.57 验证）。 要求： - 从运行此 MCP 的主机到控制器（通常为 `https://<controller-ip>`）的 LAN/VPN 可达性 - 一个**本地帐户**（查看者 / 有限管理员角色足够 — 不需要所有者凭证） - 自签名证书处理：设置 `UNIFI_LOCAL_INSECURE=true` 以适用于股票 UDM Pro 身份验证流程：`POST /api/auth/login`（cookie）→ 所有后续调用重用会话，401 触发自动重新登录。只读。 ## 配置 | 变量 | 必需 | 默认值 | 描述 | |---|---|---|---| | `UNIFI_API_KEY` | ✅ | — | 来自 unifi.ui.com 的 API 密钥（任何管理员角色） | | `UNIFI_API_KEY_OWNER` | ❌ | — | 所有者角色 API 密钥 — 启用 35 个云连接器工具。如果您的密钥具有所有者角色，请将其设置为相同的值。 | | `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 绑定主机（自动为 localhost 启用 DNS 绑定保护） | | `MCP_HTTP_SKIP_AUTH` | ❌ | `false` | 跳过 Bearer 身份验证 — 例如，在反向代理处理它 | | `UNIFI_LOCAL_URL` | ❌ | — | 本地控制器 URL（例如 `https://10.10.1.1`）。设置此项 + 用户名/密码启用 2 个 `local` 类别工具。 | | `UNIFI_LOCAL_USER` | 条件 | — | 控制器本地帐户用户名（设置 `UNIFI_LOCAL_URL` 时需要）。查看者/有限管理员角色足够。 | | `UNIFI_LOCAL_PASS` | 条件 | — | 控制器本地帐户密码（设置 `UNIFI_LOCAL_URL` 时需要）。 | | `UNIFI_LOCAL_SITE` | ❌ | `default` | 旧版 `/api/s/{site}/*` 的站点 slug。 | | `UNIFI_LOCAL_INSECURE` | ❌ | `false` | 接受自签名证书（适用于 UDM Pro）。 | **类别**（9）：`analysis`、`raw`、`devices`、`clients`、`networks`、`firewall`、`wan`、`reference`、`local`。 当 `MCP_TRANSPORT=http` 时：`POST /mcp`（带有身份验证的 JSON-RPC）+ `GET /health`（公开的活动检查）。 ### 令牌效率 所有 `@us-all/*` MCP 中最小的模式占用量。 | 场景 | 工具 | 模式令牌 | |----------|------:|--------------:| | 默认无所有者 | 17 | 1,700 | | `UNIFI_TOOLS=analysis` | 8 | **1,000** (−42%) | | 默认所有者密钥 | 52 | ~5,000 | | `UNIFI_TOOLS=analysis` + 所有者 | 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` 提供。四个属于舰队操作，四个属于 MSP 特定（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` — 排查“站点 X 的互联网速度慢”问题，通过 WAN 趋势 + ISP 指标 + 客户端 + DPI 类别 + 最近重启。 ## MCP 资源 - `unifi://site/{hostName}/devices` — 站点的设备快照 - `unifi://reboots/recent` — 最近重启的设备（全fleet范围） ## 工具（54 + 2 可选本地） 9 类别。使用 `search-tools` 在运行时发现；完整的工具列表在下面折叠。云连接器工具（33）仅在设置 `UNIFI_API_KEY_OWNER` 时注册；否则界面为 19 种工具。本地控制器工具（2）仅在设置 `UNIFI_LOCAL_URL/USER/PASS` 时注册。 | 分组 | 工具 | |-------|------:| | 语义分析（包括聚合） | 9 | | 站点管理器原始 | 9 | | 云连接器（设备/客户端/网络/ WiFi / 防火墙 / WAN / 引用） | 33 | | 本地站点（`list-local-sites`, `get-app-info`) | 2 | | **本地控制器** (`get-port-errors`, `list-port-flap-summary`) | 2 | | 元数据（`search-tools`） | 1 | <details> <summary>完整的工具列表</summary> ### 语义分析（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` *(聚合)* ### 站点管理器 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` ### 云连接器 — 设备（4） `get-device-details`, `get-device-by-id`, `get-device-statistics`, `list-pending-devices` ### 云连接器 — 客户端（2） `list-site-clients`, `get-client-details` ### 云连接器 — 网络（3） `list-networks`, `get-network-details`, `get-network-references` ### 云连接器 — WiFi（2） `list-wifi-broadcasts`, `get-wifi-broadcast-details` ### 云连接器 — 防火墙 / 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` ### 云连接器 — 流量 / WAN / VPN（5） `list-traffic-matching-lists`, `get-traffic-matching-list`, `list-wans`, `list-vpn-tunnels`, `list-vpn-servers` ### 云连接器 — 热点 / 引用（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` 对端口进行舰队范围排名。显示站点中不稳定的电缆/收发器/网卡/电源节省端点。计数器在查询之间保持一致（仅在交换机重启时重置）。 ### 元数据 `search-tools` — 按关键字查询其他工具；始终启用。 </details> ## 架构 ``` Claude → MCP stdio → src/index.ts ├── tools/analysis.ts → 站点管理器 API (UNIFI_API_KEY) ├── tools/*.ts (raw) → 站点管理器 API (UNIFI_API_KEY) ├── tools/connector.ts → 云连接器 (UNIFI_API_KEY_OWNER) └── tools/local-ports.ts → 本地控制器 (UNIFI_LOCAL_URL + LAN) helpers/resolver.ts → 主机名 ↔ ID 映射 ``` 在 [`@us-all/mcp-toolkit`](https://github.com/us-all/mcp-toolkit) 上构建： - `extractFields` — 令牌高效的响应投影 - `aggregate(fetchers, caveats)` — `summarize-site` / `site-health-timeline` 的扇出帮助程序 - `createWrapToolHandler` — `X-API-KEY` 消除 + `ConnectorError`/`UniFiError` 提取 - 重试：3 次尝试，指数退火（1 秒 → 2 秒 → 4 秒）+ 抖动，30 秒云连接器超时 ## 限制 - **只读** — UniFi API 密钥不支持写入（完整访问角色在 GA 中灰显）。 - **速率限制** — 稳定版 v1 为 10,000 req/min；早期访问版为 100 req/min。 - **云连接器部分代理** — 网络集成 API 正常工作；旧路径返回 404；事件日志/系统日志未公开。 - **ISP 指标** — 根据帐户/计划可能会返回 404。 ## 技术栈 Node.js 22+ • TypeScript 严格 ESM • pnpm • `@modelcontextprotocol/sdk` • zod v4 • dotenv. ## 许可证 [MIT](./LICENSE)