unifi-network

UniFi Network MCP 服务

依赖项

必需：network 可选：无

收集数据前，请通过 MCP 发现功能验证所需工具；仅完成发现并不能证明控制器已连接或已获授权。如果缺少必需的服务或工具，或者必需的读取操作失败，请停止并报告该项不可用。只有在报告中明确指出缺失的数据源及其造成的覆盖范围限制时，才可跳过可选数据源。需要连接帮助时，请使用产品设置技能；切勿索要密钥。

覆盖范围和限制

每份报告都必须包含 覆盖范围和限制 部分：列出每个请求的数据源及其状态（可用、不可用、部分可用或达到上限），请求的时间范围／时区或当前状态的采集时间、实际筛选条件、返回数量、限制、分页情况，以及任何失败的调用或未知字段。数量表示检索到的记录数，除非已确认数据完整，否则不代表总数。成功的空查询是一项观测；失败或缺失的数据源属于不可用，绝不能视为空结果。如果达到上限，请将数据源标记为达到上限，除非进一步的有界读取已确认覆盖范围。如果无法确认完整性，请将其标记为部分可用。对于不可用、部分可用或达到上限的数据，不要声称覆盖完整、一切正常或整体健康；适当时请说明“在检索到的记录中未发现令人担忧的活动”。

请分别列出 观测（注明来源／工具，以及可用时的记录 ID 和时间戳）、假设（相关性和其他可能解释）和 身份（仅限有明确来源依据的凭据／账户归属，并说明其限制）。仅凭时间、相似名称、接近程度或缺少匹配事件，既不能证明身份，也不能证明原因。凭据事件标识的是记录中显示的账户，而不是实际使用账户的人。映射缺失或时钟不确定会限制相关性判断。

你可以使用 UniFi Network MCP 服务查询和管理 UniFi Network Controller。它提供 210 种工具，涵盖设备、客户端、防火墙、VPN、路由、WLAN、流量流、统计信息等。

工具发现

该服务默认使用 延迟加载——初始只注册元工具。使用这些工具查找并调用任意工具：

元工具	用途
unifi_tool_index	按名称／描述发现工具；使用 category、search 或 include_schemas 进行筛选
unifi_execute	按名称调用任意工具（延迟加载模式下必不可少）
unifi_batch	并行运行多个工具
unifi_batch_status	检查异步批处理作业状态

**工作流：**调用 unifi_tool_index 查找合适的工具，然后调用 unifi_execute。对于多个相互独立的查询，请使用 unifi_batch——它比顺序调用快得多。

安全模型

该服务默认采用“安全优先”设计，因为它会控制真实的网络基础设施。

读取操作——始终可用。所有 list_*、get_* 和查询工具均无需特殊权限即可使用。

变更操作——受权限控制，默认设置各不相同：

• **默认启用：**防火墙策略、端口转发、流量路由、QoS 规则、VPN 客户端、ACL 规则、访客券、用户组
• **默认禁用（高风险）：**网络、WLAN、设备、客户端、路由、VPN 服务器
• 删除操作——默认始终禁用

如果变更操作因权限错误而失败，请告知用户需要设置的环境变量：UNIFI_POLICY_NETWORK_<CATEGORY>_<ACTION>=true。请使用错误信息中给出的确切变量名：<CATEGORY> 是服务的配置键（CLIENT_GROUPS、FIREWALL_POLICIES、OON_POLICIES），而不是 tools_manifest.json 中的 permission_category 简写（client_group、firewall、oon_policy）；根据简写构造的变量永远不会被读取。

确认流程——每项变更操作都必须先预览，再确认：

1. 默认调用 → 返回将要发生的更改预览
2. 使用 confirm=true 调用 → 执行变更

始终先预览，并在确认前向用户展示。

响应格式

所有工具都会返回：{"success": true, "data": ...}、{"success": false, "error": "..."} 或 {"success": true, "requires_confirmation": true, "preview": ...}。始终先检查 success。网络／WLAN 和 VPN 状态的写入会在执行后回读，并同时报告 mutation_applied、partial_success、persisted_fields、unchanged_fields、dropped_fields、coerced_fields 以及实际的写入后详细信息。已满足条件的无操作字段会出现在 unchanged_fields 中，不会导致失败的写入被视为部分成功。已确认的写入失败并不一定会回滚；重试或执行补偿操作前，请先检查这些字段。

已脱敏的机密信息： 默认情况下，机密字段——WLAN 密码短语（x_passphrase）、VPN 私钥／预共享密钥、完整 VPN 配置内容（导入的 WireGuard/OpenVPN 配置文件）、SNMP 团体字符串、SNMPv3 密码以及设备 SSH 凭据——会以 ***REDACTED*** 返回。原始值由进程策略控制（UNIFI_NETWORK_REDACT_SENSITIVE_FIELDS=false 或全局设置 UNIFI_REDACT_SENSITIVE_FIELDS=false），而非由工具参数控制。更新时，只发送需要更改的字段——若要保持机密信息不变，请省略该字段；切勿将 ***REDACTED*** 原样传回，否则请求会被拒绝，以防占位符覆盖真实机密信息。