UISP

UISP MCP 服务

面向 Ubiquiti UISP REST API（/nms/api/v2.1）的 MCP 服务，可查询 UISP 网络／ISP 管理实例中的站点、设备、停机事件（告警界面）、事件／审计日志、数据链路、网关、后台任务、可用固件和速度测试，供 AI 助手和 WYRE Conduit 网关使用。

身份验证

UISP 使用静态的账户令牌进行身份验证，该令牌在 UISP 控制台的 Settings -> Users -> API tokens 下生成（令牌可设为只读或读写模式；请为此连接器生成只读令牌）。UISP 没有共享的多租户端点：每个部署都运行在各自的实例 FQDN 上，包括 Ubiquiti 自己的托管云层级，因此此连接器需要同时提供令牌和基础 URL。令牌会作为 x-auth-token 标头发送到 <base URL>/nms/api/v2.1/...。在网关模式下，两者会通过 X-UISP-Api-Key 和 X-UISP-Base-URL 标头随每个请求传入；在本地／stdio 模式下，则从 UISP_API_KEY 和 UISP_BASE_URL 读取一次。

凭据范围

由供应商文档说明，未经实时实例独立验证（见下文“验证”）：UISP 自己的控制台允许在创建令牌时将其设为“Read Only”或“Read/Write”模式——这是一种真正受供应商支持的方式，可在令牌交给此连接器之前将其限定为只读；而本产品组合中的一些供应商并非如此，它们的密钥始终继承创建密钥的用户的全部权限。此连接器自身的代码只会发出 GET 请求（见下文“范围”），但“禁止写入”的执行由 UISP 负责，而非此连接器；签发只读令牌是客户的保障，并非此连接器能够从外部强制实现的。

还有一个密切相关的发现值得明确说明：UISP 同时是网络管理平台和轻量级 ISP CRM（UCRM）——此 API 中的 Site 可以包含关联的 ucrm.client 引用，其中包含真实客户的姓名，而 uisp_list_site_clients 会返回客户记录。正因如此，即使一些工具看起来只是普通的基础设施清单查询，它们也被明确归类为 isAdmin: true；详情请见下文“范围”以及 Conduit 的 vendor-config.ts 中此连接器对应的条目。

验证

此连接器直接基于 UISP 自己生成的 OpenAPI／Swagger 规范构建（标题为 UISP API，swagger: "2.0"，basePath: /nms/api/v2.1，securityDefinitions.UserSecurity 指定 x-auth-token 标头）——每个 UISP 安装都会在 https://<instance>/nms/api-docs/ 发布实时 Swagger UI，此连接器的工具均已逐一对照该规范记载的 180 个 GET 操作进行验证，而非依据二手文档或命名约定。但此连接器未经实时 UISP 实例的独立验证：UISP 按 ISP 部署（可自托管；Ubiquiti 的托管云层级则要求拥有活跃的 ISP／网络运营商账户），而此构建环境中没有可用实例，无法使用真实令牌完成端到端测试。这是构建环境的限制，并非供应商的审批门槛——ISP 运营商确实可以自行注册使用托管云层级。

配置

环境变量	说明
UISP_API_KEY	在 UISP 控制台签发的账户令牌。
UISP_BASE_URL	UISP 实例的基础 URL，例如 https://uisp.example.com。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，读取上述变量）或 gateway（凭据通过 X-UISP-Api-Key／X-UISP-Base-URL 标头随每个请求传入，由 Conduit 网关注入）。
CONDUIT_S2S_SECRET	设置后，HTTP 传输要求每个 /mcp 请求都携带有效的 X-Gateway-S2S 标头（Conduit sidecar 身份验证）。
LOG_LEVEL	debug | info（默认）| warn | error。

请求限制

• HTTP 请求正文上限为 256 KiB（262144 bytes）。通过 X-Gateway-S2S 检查后，如果 Content-Length 超过上限，则返回 413 和 JSON-RPC 错误；没有 Content-Length 的正文由 MCP SDK 传输层限制。未通过身份验证的请求仍会优先返回 401。
• tools/call 参数上限为 10,000 个元素（包括任意深度的每个数组项和对象键）。超出限制的输入会返回 isError 工具结果，且不会被分发。

这些限制用于应对 CVE-2026-111768 / GHSA-46jr-4wx8-v453（验证期间内存耗尽）和 GHSA-f897-62hf-6gxq（缺少请求正文／批次上限）。

工具

站点

• uisp_list_sites - 列出站点（网络位置——站点、端点和客户端——每个站点都可以选择关联到 UCRM 客户端／服务记录）。
• uisp_get_site - 获取单个站点的详细信息。
• uisp_search_sites - 按名称、地址、MAC 地址或 IP 地址搜索站点／端点／客户端。
• uisp_list_site_clients - 列出属于指定（父级）站点的所有客户端站点。
• uisp_get_site_statistics - 获取站点与其父级站点之间的上传／下载流量。
• uisp_get_site_traffic_summary - 获取指定时间间隔内截至当前的站点总上传／下载量。

设备

• uisp_list_devices - 列出设备（主机名／IP／MAC、状态、父级站点）。
• uisp_get_device - 获取单个设备的状态概览。
• uisp_get_device_detail - 获取设备详细信息，可选择包含接口和／或已连接的终端。
• uisp_get_device_statistics - 获取设备遥测数据（CPU／RAM／信号／温度／吞吐量）。
• uisp_list_device_interfaces - 列出设备的网络接口，包括已配置的 IP 地址。
• uisp_get_device_by_mac - 按 MAC 地址查找设备。
• uisp_list_discovered_devices - 列出已在网络中发现但尚未添加的设备。

中断

• uisp_list_outages - 列出网络中断——UISP 的告警界面——可按设备、类型和是否正在处理中筛选。

日志

• uisp_list_logs - 列出 UISP 事件／审计日志（登录、设备状态变更、备份、升级）。

数据链路

• uisp_list_data_links - 列出数据链路（UISP 映射的设备与站点之间的无线／有线链路）。
• uisp_get_data_link - 获取单条数据链路的详细信息。
• uisp_list_site_data_links - 列出关联到指定站点的数据链路。

网关

• uisp_list_gateways - 列出网关（配置为网络网关的路由器）及其 NetFlow/QoS/暂停配置。
• uisp_get_gateway - 获取单个网关的详细信息。

任务

• uisp_list_tasks - 列出后台任务（固件升级、备份、批量操作）及其状态。
• uisp_get_tasks_in_progress - 获取当前正在处理的任务数量。

固件

• uisp_list_firmwares - 获取 UISP 为其支持的设备型号提供的固件版本。

速度测试

• uisp_get_speed_tests - 获取正在运行和近期速度测试的详细信息。

系统

• uisp_get_version - 获取 UISP 版本、部署类型和构建信息。可用于检查凭据／连接是否正常。
• uisp_get_network_statistics - 获取全网统计信息（客户端／站点数量、网络健康状况、信号／链路／ISP 评分、中断次数）。
• uisp_get_summary - 获取整个实例中类似徽章计数的数值（未读日志／中断／固件数量、活跃客户端／站点数量）。

范围

这是一个有意精简的只读 v1 功能面，严格涵盖 NOC/MSP 监控的核心工作流——站点和设备清单、状态、遥测数据、服务中断和审计日志——不包含其他内容。 UISP 自带的 OpenAPI 规范记录了 325 个路径（其中 180 个为 GET），涵盖范围广泛得多：完整的网络/设备配置与部署、CRM/计费、用户和 API 令牌管理、设备凭据存储、备份、服务器管理，以及规划/模拟工具。本连接器从该规范中实现了 27 个 GET 操作，逐一验证，并且是有意排除其他所有内容，而非疏忽遗漏。

明确排除（设备凭据库）——从未实现： GET /vault/credentials、/vault/credentials/devices、/vault/{deviceId}/credentials——这实际上是设备登录凭据存储库；无论 HTTP 方法为何，均直接排除。

明确排除（API 令牌/用户/访问组管理——身份与凭据管理，不属于网络数据）——从未实现： GET /token、/token/{tokenId}、/users、/user、/user/totpauth、/access-groups/sites、/access-groups/sites/{groupId}、/nms/keep-alive、/nms/account/login/ubiquiti。

明确排除（备份、还原和支持包下载——涉及二进制/敏感数据；即使提供还原操作所需数据的读取使用 GET，还原本身也属于与写入相关的维护操作）——从未实现： GET /nms/backups、/nms/backups/{backupId}、/nms/backups/{backupId}/download-token、/nms/downloads/{token}、/nms/maintenance/backup、/nms/maintenance/backup/restore、/nms/maintenance/supportinfo、/devices/{deviceId}/backups、/devices/{deviceId}/backups/{backupId}、/devices/{id}/supportfile。

明确排除（服务器管理和设置——可能包含邮件服务器/SMTP 凭据及服务器级配置，不属于网络/设备数据）——从未实现： GET /nms/settings、/nms/server-config、/nms/setup、/nms/mailserver、/nms/connection（返回 UISP 服务器自身的连接密钥）、/nms/log-verbosity、/nms/update、/nms/update/log、/nms/traffic/blacklist、/nms/traffic/subnets、/nms/address、/nms/search、/nms/news、/nms/blog/posts、/nms/questionnaires/active、/nms/changed、/nms/server-time、/nms/heartbeat（仅检查未经过身份验证的存活状态；本连接器改用经过身份验证的 uisp_get_version 进行健康检查）。

明确排除（CRM/计费——独立子系统，使用自己的客户计费数据模型，不属于网络监控连接器的范围）——从未实现： GET /crm/roles、/crm/service-plans。

明确排除（GDPR/客户数据导出）——从未实现： GET /gdpr/clients/{id}——以格式化形式导出单个客户的个人数据。

明确排除（原始设备透传/UDAPI 代理）——从未实现： GET /devices/{deviceId}/udapi/{version}/{udapiUrl*}——通用反向代理，直通设备自身的本地 API；UISP 自带的规范并未限制目标端必须遵循 GET 语义，因此无论外层 HTTP 方法为何，该类别均予以排除，处理方式与 unifi-mcp 对其类似的按控制台划分的连接器代理路径相同。

明确排除（网络发现控制平面）——从未实现： GET /discovery/scan-status、/discovery/status/{deviceId}——用于查询活动网络扫描的状态，而该扫描是在 API 的其他位置触发/控制的；作为同一发现工作流的一部分予以排除，不单独拆分处理。 严格排除（深入的逐设备配置：DHCP、防火墙、路由、VLAN、NetFlow、无线/AirCube/AirMax/OLT/ONU 配置）——从未实现： /devices/erouters/*、/devices/uisprs/*（DHCP 租约/服务器、防火墙过滤器/修改规则/NAT/集合/设置、OSPF、路由、NetFlow）、/devices/{id}/router/*、/devices/{id}/netflow、/devices/{id}/vlans、/devices/{id}/services、/devices/{id}/system、/devices/{id}/system/unms、/devices/{deviceId}/mac-table*、/devices/{deviceId}/interfaces/{interfaceName}、/devices/{deviceId}/interfaces/data-link/available、/devices/{deviceId}/location 下的所有 GET 请求，以及按设备型号划分的详情/配置/站点端点系列（/devices/aircubes/*、/airfibers/*、/airmaxes/*、/blackboxes/*、/epowers/*、/eswitches/*、/olts/*、/onus/*、/solarbeams/*、/toughswitches/*、/uispss/*、/waves/*，以及 /devices/aps/profiles、/devices/ssids、/devices/models、/devices/macs、/devices/ips、/devices/unknown、/devices/import/status）——此连接器的设备接口有意仅限于身份/状态/遥测/接口（uisp_list_devices、uisp_get_device、uisp_get_device_detail、uisp_get_device_statistics、uisp_list_device_interfaces、uisp_get_device_by_mac、uisp_list_discovered_devices），不包括按供应商型号划分的配置。

严格排除（超出核心六项的网站子资源）——从未实现： GET /sites/{id}/images、/sites/{siteId}/images/{imageId}（二进制）、/sites/{siteId}/qos、/sites/{siteId}/slastats（UISP 自己的摘要将其描述为“用于 ISP 和 SLA 评分调试”）、/sites/{siteId}/traffic、/sites/{siteId}/traffic/interval、/sites/traffic（就此连接器的用途而言，已由已实现的 uisp_get_site_traffic_summary 取代）。

严格排除（规划/模拟和现场安装工具——不属于实时网络状态）——从未实现： GET /simulation、/simulation/devices、/simulation/links、/installations/devices、/installations/{id}、/installations/{id}/{mac}/configuration。

严格排除（其他）——从未实现： GET /devices/{id}/router/*（见上文）、/tasks/{batchId}（已实现的列表/进行中数量之外的单任务详情）、/airlink/proxy/*（RF 链路规划地图/高程数据文件，与实时网络状态无关）、/nms/version/latest（检查是否有较新的 UISP 版本；属于管理功能，不是监控数据）。

如有需求，可在审慎决定范围后作为后续工作添加——默认不会添加。

开发

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

docker build -t uisp-mcp .
docker run -p 8080:8080 -e UISP_API_KEY=... -e UISP_BASE_URL=https://uisp.example.com uisp-mcp