Unifi MCP (Abl030)

MCPAI代理

提供方 abl030

AI代理 stdio · 本地进程 会话登录 社区 / 第三方 Claude
查看接入方式

一个为AI代理提供全面控制Ubiquiti UniFi网络基础设施的模型上下文协议服务器,包含286个工具覆盖网络配置、设备管理等功能。

一句话选型结论

按资料字段整理

Unifi MCP (Abl030) 属于AI代理类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 294 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量294暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

网络管理Python本地部署AI控制UniFi集成自动化运维协议服务器

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
uv run python generate.py

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 294 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 294 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Unifi MCP (Abl030)当前 294 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方abl030上游标注的维护方 abl030
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

29.0 KB
来自项目仓库与上游目录的原文,未做删改

UniFi MCP服务器

MCP(模型上下文协议)服务器,使AI代理能够完全控制Ubiquiti UniFi网络基础设施。 286工具 涵盖网络、防火墙规则、交换机端口、WiFi、客户端、设备命令、热点管理、DPI、站点设置等。

整个项目——生成器、服务器、测试套件和此README——由AI(Claude)构建,旨在供AI代理安装和使用。

安装此MCP服务器

选项1:镍片(推荐)

这个回购是Nix薄片。将其作为输入添加到NixOS配置或任何flake中,您将得到一个自包含的 unifi-mcp 二进制文件,所有依赖项都捆绑在一起。更新是单一的 nix flake update.

添加到您的薄片输入中:```nix

flake.nix

{
inputs = {
unifi-mcp.url = "github:abl030/unifi-mcp";
};
}


**使用软件包:**```nix
# The binary is at: inputs.unifi-mcp.packages.${system}.default
# It provides: unifi-mcp (runs fastmcp with the server)

# Example: add to systemPackages
environment.systemPackages = [ inputs.unifi-mcp.packages.${pkgs.system}.default ];

# Example: use in an MCP server config
{
command = "${inputs.unifi-mcp.packages.${pkgs.system}.default}/bin/unifi-mcp";
env = {
UNIFI_HOST = "192.168.1.1";
UNIFI_USERNAME = "admin";
UNIFI_PASSWORD = "your-password";
};
}

无需安装即可快速测试:```bash
UNIFI_HOST=192.168.1.1 UNIFI_PASSWORD=secret nix run github:abl030/unifi-mcp


**本地构建:**```bash
nix build github:abl030/unifi-mcp
./result/bin/unifi-mcp  # starts the MCP server on stdio

选项2:uv(非Nix)```bash

git clone https://github.com/abl030/unifi-mcp.git
cd unifi-mcp
uv sync
uv run python generate.py


这产生 `generated/server.py` --配备286个工具的MCP服务器。

### 配置您的MCP客户端

**克劳德代码** (`claude mcp add`):```bash
# Nix — uses the flake binary directly
claude mcp add unifi -- \
env UNIFI_HOST=YOUR_CONTROLLER_IP \
UNIFI_PORT=8443 \
UNIFI_USERNAME=admin \
UNIFI_PASSWORD=YOUR_PASSWORD \
UNIFI_SITE=default \
unifi-mcp

# Non-Nix — uses uv to run
claude mcp add unifi -- \
env UNIFI_HOST=YOUR_CONTROLLER_IP \
UNIFI_PORT=8443 \
UNIFI_USERNAME=admin \
UNIFI_PASSWORD=YOUR_PASSWORD \
UNIFI_SITE=default \
uv run --directory /path/to/unifi-mcp fastmcp run generated/server.py

克劳德桌面 (claude_desktop_config.json):```json
{
"mcpServers": {
"unifi": {
"command": "unifi-mcp",
"env": {
"UNIFI_HOST": "YOUR_CONTROLLER_IP",
"UNIFI_PORT": "8443",
"UNIFI_USERNAME": "admin",
"UNIFI_PASSWORD": "YOUR_PASSWORD",
"UNIFI_SITE": "default"
}
}
}
}


### 环境变量

|变量|默认值|描述|
|----------|---------|-------------|
| `UNIFI_HOST` | `localhost` |控制器主机名或IP|
| `UNIFI_PORT` | `8443` |控制器HTTPS端口|
| `UNIFI_USERNAME` | `admin` |管理员用户名|
| `UNIFI_PASSWORD` | *(必填)* |管理员密码|
| `UNIFI_SITE` | `default` |站点名称|
| `UNIFI_VERIFY_SSL` | `false` |验证SSL证书|
| `UNIFI_MODULES` | `v1,v2` |要注册的工具组(见下文)|
| `UNIFI_READ_ONLY` | `false` |删除所有变异工具(见下文)|
| `UNIFI_REDACT_SECRETS` | `true` |替换敏感字段(`x_passphrase`、密码等) `` 在回应中|

### 模块切换(`UNIFI_MODULES`)

控制在运行时注册哪些工具组。使用细粒度模块只加载您需要的内容,从而降低LLM的噪音。

**捷径** (向后兼容):

|价值|工具|用例|
|-------|-------|----------|
| `v1,v2` (默认)|286|所有工具(UniFi OS控制器)|
| `v1` |270|所有v1工具(独立控制器,无v2端点)|
| `v2` |仅限25 |v2+全局工具|

**细粒度模块** (混合搭配):

|模块|工具|包括什么|
|--------|-------|-----------------|
| `device` |33|设备命令(采用/重启/升级/定位)、设备统计信息、端口覆盖|
| `client` |17 |客户端阻塞/踢/忘记,用户CRUD,客户端统计,v2活动/历史客户端|
| `wifi` |15 | WLAN配置、WLAN组、信道计划、v2 AP组|
| `network` |15 |网络/VLAN、端口配置文件、DNS记录|
| `firewall` |42 |防火墙规则/组、端口转发、路由、DDNS、DHCP、v2策略/区域/流量|
| `monitor` |34|所有统计端点、警报、事件、报告、DPI统计|
| `admin` |41 |设置、用户组、标签、帐户、站点/管理员管理、备份|
| `hotspot` |32 |热点操作/套餐、热点2、RADIUS、优惠券、访客命令|
| `advanced` |46 |地图、热图、空间、DPI配置、媒体、时间表、广播|

上述工具计数包括每个模块的v1和v2工具。全球工具(11: `status`, `self`, `sites`等等。 + `report_issue` + `get_overview` + `search_tools`)无论此设置如何,始终都会注册。

**示例**:管理交换机和AP的独立控制器:```bash
UNIFI_MODULES=device,client,wifi,network,monitor  # 124 tools instead of 286

无需再生——只需设置env变量即可。

只读模式(UNIFI_READ_ONLY)

集 UNIFI_READ_ONLY=true 在注册时删除所有变异工具。仅注册了列表、获取和统计工具,MCP工具列表中不存在创建、更新、删除、重新启动、重新引导或任何其他状态更改操作。

配置 工具 用例
UNIFI_READ_ONLY=false (默认) 286 完全访问
UNIFI_READ_ONLY=true 125 仅监测——零突变风险
UNIFI_MODULES=device,client,monitor UNIFI_READ_ONLY=true 51 重点监控

作曲与 UNIFI_MODULES --两个过滤器独立应用。只读模式在工具注册时强制执行,而不是在运行时:MCP工具列表中不存在变异工具,因此即使有指示,LLM也无法调用它们。

您将获得:285个工具

网络配置(CRUD——每个工具5个)

资源 工具 描述
网络 list / get / create / update / delete VLAN、子网、DHCP(rest/networkconf)
防火墙规则 list / get / create / update / delete L3/L4防火墙规则
防火墙组 list / get / create / update / delete 规则的IP/端口组
港口货运 list / get / create / update / delete NAT端口转发
端口配置文件 list / get / create / update / delete 交换机端口配置文件
WLAN list / get / create / update / delete WiFi网络
WLAN组 list / get / create / update / delete WiFi网络组
路线 list / get / create / update / delete 静态路线
动态DNS list / get / create / update / delete DDNS条目
RADIUS配置文件 list / get / create / update / delete RADIUS身份验证配置文件
RADIUS帐户 list / get / create / update / delete RADIUS用户帐户
用户组 list / get / create / update / delete 客户群
用户 list / get / create / update 已知客户端(通过删除 forget_client)
标签 list / get / create / update / delete 设备/客户端标签
账户 list / get / create / update / delete RADIUS帐户

热点和访客管理(CRUD)

资源 工具 描述
热点运营商 list / get / create / update / delete 热点门户运营商
热点套餐 list / get / create / update / delete 热点计费套餐
热点2配置 list / get / create / update / delete 热点/热点2.0
优惠券 create_voucher / revoke_voucher / delete_voucher 访客入场券
访客身份 hotspot_authorize_guest / extend_guest_validity 访客会话管理

现场测绘和空间(CRUD)

资源 工具 描述
地图 list / get / create / update / delete 现场平面图
热图 list / get / create / update / delete WiFi覆盖热图
热图点 list / get / create / update / delete 热图数据点
空间记录 list / get / create / update / delete 设备定位

DPI和网络智能(CRUD)

资源 工具 描述
DPI应用程序 list / get / create / update / delete 应用定义
DPI组 list / get / create / update / delete DPI限制组
DNS记录 list / get / create / update / delete 本地DNS记录
DHCP选项 list / get / create / update / delete 自定义DHCP选项
广播组 list / get / create / update / delete 多播组
安排任务 list / get / create / update / delete 预定操作
媒体文件 list / get / create / update / delete 门户媒体文件

只读资源(每个工具1个)

工具 说明
unifi_list_device_configs 设备配置(使用 set_port_override 修改)
unifi_list_channel_plans WiFi频道计划
unifi_list_virtual_devices 虚拟/逻辑设备
unifi_list_known_rogue_aps 已知/邻近AP
unifi_list_elements 元素平台设备
unifi_list_alarms 报警历史记录
unifi_list_events 事件日志

设置(3个工具)

工具 说明
unifi_list_settings 全部38个设置类别
unifi_get_setting 按键获取特定设置
unifi_update_setting 更新设置(需要确认)

设备监控(39个统计工具)

工具 说明
unifi_list_devices 所有采用的设备,详细信息
unifi_list_clients 已连接的客户端(IP、MAC、信号、流量)
unifi_list_health 网络健康子系统
unifi_list_rogue_aps 检测到恶意访问点
unifi_list_sessions 客户端会话历史记录
unifi_list_sysinfo 系统信息
unifi_list_devices_basic 设备(基本信息)
unifi_list_guests 客人客户
unifi_list_dashboard 仪表板时间序列数据
unifi_list_all_users 所有用户(历史)
unifi_list_vouchers 热点优惠券
unifi_list_gateway_stats 网关设备统计信息
unifi_list_dpi_stats DPI统计
unifi_list_anomalies 网络异常
unifi_list_ips_events IDS/IPS事件
unifi_list_remote_user_vpn 远程VPN会话
unifi_list_sdn_status SDN连接状态
unifi_list_spectrum_scans 射频频谱扫描结果
unifi_list_stat_alarms / stat_events 统计级报警/事件数据
unifi_list_site_dpi / client_dpi 每个站点/客户端的DPI统计数据
unifi_list_country_codes / current_channels 参考数据
unifi_list_routing_stats / authorizations / payments 其他统计数据
unifi_list_dynamic_dns_stats / port_forward_stats 服务统计
unifi_list_report 报告(5分钟/小时/每天/每月)
unifi_list_speedtest_results 存档的速度测试结果
unifi_list_report_* 8个特定的报告端点(网关、AP、站点、用户为5分钟/小时/每天/每月)

设备命令(28个devmgr命令)

工具 说明
unifi_restart_device 重新启动设备
unifi_adopt_device / advanced_adopt_device 采用新设备
unifi_locate_device / unlocate_device 闪光设备LED
unifi_upgrade_device / upgrade_device_external / upgrade_all_devices 固件升级
unifi_rolling_upgrade / cancel_rolling_upgrade 滚动固件升级
unifi_check_firmware_update 检查固件更新
unifi_force_provision_device 部队重新配置
unifi_power_cycle_port PoE电源关闭开关端口
unifi_run_speedtest / get_speedtest_status 速度测试
unifi_spectrum_scan 射频频谱扫描
unifi_cable_test 交换机端口电缆诊断
unifi_rename_device 重命名设备
unifi_led_override_device 超控设备LED模式
unifi_enable_device / disable_device / disable_ap 启用/禁用设备
unifi_migrate_device / cancel_migrate_device 设备迁移
unifi_set_inform_device 设置设备通知URL
unifi_set_rollupgrade / unset_rollupgrade 滚动升级标志
unifi_restart_http_portal 重新启动专属门户

客户端命令(7个stamgr命令)

工具 说明
unifi_block_client / unblock_client 阻止/取消阻止客户端
unifi_kick_client 断开客户端连接
unifi_forget_client 删除客户端历史记录
unifi_reconnect_client 强制客户端重新连接
unifi_authorize_guest / unauthorize_guest 访客门户认证

站点和管理(14个sitemgr命令)

工具 说明
unifi_add_site / delete_site / update_site 站点CRUD
unifi_set_site_leds 现场LED控制
unifi_get_admins 列出管理员用户
unifi_create_admin / invite_admin / assign_existing_admin 添加管理员
unifi_update_admin / revoke_admin 管理管理员
unifi_grant_super_admin / revoke_super_admin 超级管理员权限
unifi_move_device / delete_device 跨站点设备操作

备份和系统(8个命令)

工具 说明
unifi_list_backups / delete_backup 管理备份
unifi_create_backup / generate_backup / generate_backup_site 创建备份
unifi_download_backup 下载备份文件
unifi_reboot_cloudkey 重新启动CloudKey
unifi_element_adoption 元素平台采用

报警和事件管理

工具 说明
unifi_archive_all_alarms 存档所有警报(evtmgr)
unifi_archive_alarm 存档单个报警(evtmgr)
unifi_alarm_archive 通过报警管理器存档
unifi_clear_dpi 清除DPI计数器

v2 API(15个工具)

工具 说明
unifi_list_firewall_policies / create / update / delete v2防火墙策略
unifi_list_traffic_rules / create / update / delete v2交通规则
unifi_list_traffic_routes / update v2交通路线
unifi_list_firewall_zones / update v2防火墙区域
unifi_list_active_clients v2活动客户端列表
unifi_list_clients_history v2客户端历史记录
unifi_list_ap_groups v2 AP组

全球&特别

工具 说明
unifi_status 控制器状态(无需身份验证)
unifi_self 当前管理员信息
unifi_sites 列出所有网站
unifi_stat_admin / stat_sites 管理员/站点统计
unifi_logout 无效会话
unifi_system_poweroff / system_reboot 控制器电源管理(危险)
unifi_get_overview 单次通话中的网络概述:运行状况、设备、网络、WLAN、客户端、警报
unifi_set_port_override 配置交换机端口配置文件(启动此项目的工具)
unifi_search_tools 按关键字搜索工具(例如“vlan”、“防火墙规则”、“备份”)——先使用这个
unifi_report_issue 创作a gh issue create 意外错误命令

安全:确认门

所有突变工具(创建、更新、删除、设备命令)都需要 confirm=True没有它,他们就会返回一个模拟预览,预测会发生什么变化。这可以防止意外修改。```

Without confirm — returns preview only

unifi_create_network(name="Guest VLAN", purpose="vlan-only", vlan=100)

With confirm — actually creates the network

unifi_create_network(name="Guest VLAN", purpose="vlan-only", vlan=100, confirm=True)


### 错误报告

每个工具的docstring都包含一个轻推: *如果此工具返回意外错误,请调用unifi_report_issue进行报告* 这 `unifi_report_issue` 该工具编写了一个现成的粘贴工具 `gh issue create` 命令中包含工具名称、错误消息、使用的参数和可选注释。它不进行HTTP调用,只返回一个用户可以查看和运行的命令字符串。

这意味着使用此MCP服务器的LLM代理在遇到意外错误时会自动建议提交错误报告,从而创建从生产使用到维护人员的反馈循环。

### 响应格式

所有工具都返回结构化JSON。列表工具返回:```json
{"summary": "Found 5 networks", "count": 5, "data": [{...}, ...]}

单件工具退货:```json
{"data": {"_id": "abc123", "name": "My Network", ...}}


这种格式是机器可解析的——不再有双重编码的JSON侧字符串响应。

### 秘密行动

默认情况下(`UNIFI_REDACT_SECRETS=true`),敏感字段替换为 `` 在所有回复中。这可以防止WiFi密码、密码和其他秘密泄露到LLM上下文窗口中。修改后的字段包括 `x_passphrase`, `x_password`, `x_shadow`, `x_private_key`,以及包含以下内容的任何字段 `password`, `passphrase`, `secret`,或 `preshared_key`.Set `UNIFI_REDACT_SECRETS=false` 以获得原始值。

### 分页和字段选择

所有列表工具都接受三个可选参数:

|参数|默认值|说明|
|-----------|---------|-------------|
| `limit` | `0` |要返回的最大记录数(`0` =全部,向后兼容)|
| `offset` | `0` |跳过这么多记录|
| `fields` | `""` |要包含的逗号分隔的字段名(例如。 `"name,ip,mac"`) |

当 `fields` 被指定, `_id` 始终包含以供参考。这是客户端过滤——从控制器获取完整的数据集,然后切片。对于大型部署,请使用 `limit` 和 `offset` 在不压倒法学硕士背景的情况下浏览结果。```
# Get just names and subnets of the first 5 networks
unifi_list_networks(limit=5, fields="name,ip_subnet,vlan")

运作原理

此回购包含 发电机 其读取API规范并产生MCP服务器。您不需要了解生成器就可以使用服务器——只需运行 generate.py 一次。

为什么是发电机?

UniFi API没有官方的OpenAPI规范。我们没有手工编写285个工具函数,而是建立了一个多阶段发现管道,从实时控制器捕获真实的API表面,然后自动生成服务器。当Ubiquiti更新他们的API时,重新运行管道并重新生成。

建筑```

spec/
endpoint-inventory.json # API surface: 196 endpoints from real controller
probe-spec.json # Declarative endpoint list for probe
field-inventory.json # Field names from production controller
api-samples/ # 120+ real (scrubbed) JSON responses for schema inference
generate.py # Entry point: load -> infer -> render -> write
generator/
loader.py # Parse spec/ data into structured types
schema_inference.py # JSON values -> Python types + enum detection
naming.py # Tool names, command mappings, test payloads
context_builder.py # Assemble Jinja2 template context
templates/
server.py.j2 # FastMCP server template (286 tools)
conftest.py.j2 # Pytest fixtures
test_rest.py.j2 # Per-resource CRUD lifecycle tests
test_stat.py.j2 # Stat endpoint tests
test_cmd.py.j2 # Command tests
test_v2.py.j2 # v2 endpoint tests
test_global.py.j2 # Global endpoint tests
generated/ # OUTPUT — never hand-edit
server.py # The MCP server (this is what you run)
conftest.py # Test fixtures
tests/ # 44 test files


**关键规则:** 生成的代码 `generated/` 从未经过手工编辑。如果输出有错误,请修复生成器模板或模块并重新运行。

### MCP服务器内部

生成的 `server.py` 包括:

- 异步httpx客户端,具有基于cookie的身份验证和CSRF令牌处理
- 自动重新登录401个响应
- UniFi操作系统支持(手柄 `/proxy/network` 自动前缀)
- 结构化错误处理——解析 `meta.rc` / `meta.msg` 来自API响应
- 站点感知——env-var中的默认站点,每个工具覆盖可用
- 具有字段类型、枚举值和工具之间交叉引用的丰富文档字符串

## API发现管道

286工具来自一个针对真正的UniFi网络控制器v10.0.162运行的三阶段端点发现过程:

### 第一阶段:自动探头(`probe.py`)

一个单文件Python脚本,使用安全的HTTP方法系统地命中每个已知的端点路径,并记录状态代码、示例响应和字段模式。```bash
# Full automated cycle (Docker container + probe + teardown):
scripts/run_probe.sh

# Manual probe against a running controller:
uv run python probe.py --host HOST --no-verify-ssl

# Dry run — preview what would be probed:
uv run python probe.py --dry-run

安全规则是硬编码的:永远不要对 rest/,从不执行不安全的命令,从不点击 system/reboot 或 poweroff.所有敏感字段(x_password, x_passphrase, x_shadow, x_private_key等)被擦洗 "REDACTED" 在将样本写入磁盘之前。

第二阶段:LLM动力发现(llm-probe/)

在自动探测期间返回404或400的端点通过以下方式馈送给Claude claude -p (克劳德代码CLI)。对于每个端点,Claude都会分析HTTP方法、请求体或路径变化可能适用的原因,然后使用 curl 对抗实时控制器。```bash

Probe all 400-status endpoints:

python llm-probe/llm_probe.py --host localhost --port 8443 \
--username admin --password testpassword123 \
--no-verify-ssl --only-category 400

Probe 404 endpoints:

python llm-probe/llm_probe.py --only-category 404 ...


该阶段发现了44个额外的工作端点,包括:

- 全部28 `set/setting/*` 端点(仅限PUT,与配对 `get/setting/*` 阅读)
- `stat/session` (需要带日期范围正文的POST)
- `upd/user` 和 `upd/device` (用于更新资源的PUT端点)
- `group/user` (批量用户组分配)
- WebSocket事件流在 `/wss/s/{site}/events`

### 第三阶段:发电机(`generate.py`)

生成器读取发现的资源清册,并使用完整的CRUD工具、统计查询、命令包装器和v2 API工具生成MCP服务器,所有这些工具都具有从真实API响应样本推断的正确参数类型。```bash
uv run python generate.py         # Generate server + tests
uv run python count_tools.py      # Verify tool counts match

验证```

$ uv run python count_tools.py
TOOL COUNTS (computed from spec)
REST tools: 154
Stat tools: 39
Cmd tools: 66
v2 tools: 15
Global tools: 8
Port override: 1
Report issue: 1
Overview: 1
Search tools: 1
TOTAL tools: 286

VERIFICATION
Computed from spec: 286
Actual in server.py: 286
✓ MATCH


## 运行测试套件

该测试套件在Docker中针对真实的UniFi控制器运行。44个测试文件,所有验证测试均通过。```bash
# Start ephemeral controller
docker compose -f docker-compose.test.yml up -d

# Wait for it to be healthy (~60-90s), then run tests
uv run pytest generated/tests/ -v

# Tear down
docker compose -f docker-compose.test.yml down -v

模块切换测试(无需控制器)

test_modules_toggle.py 验证每个 UNIFI_MODULES 配置会加载正确的工具。所有预期值均为 自动衍生 从 spec/endpoint-inventory.json + generator/naming.py --零硬编码数字。当API表面发生变化时,这些测试将自动适应。bash uv run --extra test python -m pytest test_modules_toggle.py -v # 62 tests

它涵盖了什么(62项测试):

  • 每种配置的工具计数: v1,v2, v1, v2、空白、空格、9个子模块中的每一个单独、所有模块组合、多模块组合、, v2+module
  • 工具存在:始终在线,工具无处不在,每个模块的工具在加载时都存在
  • 互斥性:加载一个模块不会泄露其他模块的工具
  • v2双防护:v2工具可通过其父子模块和 v2 旗帜
  • 任何配置中都没有重复项
  • 仅设备模块中的端口覆盖
  • 只读模式:正确计数 v1,v2, v1, v2,空,每个子模块,组合
  • 只读安全:没有突变工具,没有 confirm 参数工具,保留始终打开的只读工具

测试原理

测试在没有采用设备的控制器上运行。我们不是跳过需要硬件的测试,而是断言正确的错误响应——证明端点是可访问的,正确验证输入,并返回正确的错误。一个断言“此端点为虚拟MAC返回400个未知设备”的测试证明该端点与快乐路径测试一样有效。有关详细信息,请参阅测试模板。

控制器引导

UniFi控制器没有安装向导API。测试工具将管理员用户直接植入嵌入式MongoDB(ace 数据库)通过 docker exec.密码哈希使用 openssl passwd -6 容器内部(Python 3.13删除了 crypt 模块)。这是完全自动化的 conftest.py.

QA覆盖范围

所有286个工具都使用基于LLM的库测试器在Docker中运行的实时UniFi v10.0.162控制器上进行了测试(Claude担任QA工程师,31个任务,在5个修复冲刺中调用498多个工具)。

“第一次尝试就成功了” 是关键的QA指标。每个工具在第一次调用时都经过验证,参数正确——没有重试、没有参数猜测、没有错误和重试循环。这很重要,因为第一次尝试失败的MCP工具浪费了令牌、上下文窗口和用户时间,因为LLM必须诊断错误并重试。首先尝试的工具意味着文档字符串、参数类型和枚举值都足够正确,LLM可以在没有先前经验的情况下成功调用它。

覆盖范围摘要

类别 工具 状态
REST CRUD 154 全部测试(28个CRUD资源+设置+只读)
统计终点 39 全部测试
命令 66 全部测试(跳过2个,见下文)
v2 API 15 所有测试
全局 8 全部测试
端口覆盖 1 已测试(需要设备才能成功)
报告问题 1 错误报告帮助程序(无API调用)
概述 1 已测试(复合:健康+设备+网络+WLAN+客户端+警报)
搜索工具 1 用于基于关键字的工具发现的元工具(无API调用)
总计 286 100%调用覆盖率

跳过的命令(未生成)

命令 管理器 原因
set-site-name sitemgr v10.0.162独立控制器上不存在。使用 update-site 相反。
delete-admin sitemgr 遗迹; revoke-admin 已经完全删除了admin对象。

跳过REST操作

资源 操作 原因
user DELETE 不支持REST DELETE。使用 forget_client (stamgr forget-sta)相反。

未经测试(需要硬件或外部服务)

这些工具存在并生成,但如果没有采用UniFi设备或外部基础设施,就无法完全使用:

依赖硬件(23种工具) --需要采用AP、交换机或网关:

  • 设备命令: adopt_device, restart_device, force_provision_device, locate_device, unlocate_device, upgrade_device, upgrade_device_external, migrate_device, cancel_migrate_device, spectrum_scan, move_device, delete_device, rename_device, power_cycle_port
  • 客户端命令: kick_client, reconnect_client (需要连接的无线客户端)
  • 热点命令: hotspot_authorize_guest, extend_guest_validity (需要热点门户)
  • 防火墙: create_firewall_policy (需要网关+区域)
  • 交通: update_traffic_route (需要网关)
  • 其他: set_site_leds (需要支持LED的设备), set_port_override (需要采用开关)

独立控制器限制(5个工具) --在UniFi操作系统上工作,但不能独立使用Docker:

  • delete_site --无论管理员权限如何,都返回NoPermission
  • generate_backup, generate_backup_site --独立cmd/backup中不存在备份生成命令

API限制(3个工具) --需要外部基础设施:

  • create_hotspot_package --需要支付网关配置
  • create_dhcp_option --需要DHCP网关设备
  • revoke_voucher --需要热点门户基础设施

破坏性(3个工具) --故意不测试:

  • logout, system_poweroff, system_reboot

致谢

API端点清单是从多个社区来源构建的。UniFi API未经Ubiquiti记录,我们所知道的一切都来自社区的反向引擎工作:

  • WiFi/UniFi-API-浏览器的艺术作品 和 WiFi/UniFi-API-客户端的艺术作品 -UniFi API最全面的社区文档。许多端点路径、命令名和参数模式都来自它们的PHP客户端和API浏览器。
  • 非加油员/非加油员 (以前称为unifi poller)--统计、异常、IPS/IDS事件和DPI数据收集的端点路径。
  • py unifi --Python UniFi客户端,具有OpenAPI规范贡献,有助于发现REST端点,如 dhcpoption, heatmap, heatmappoint, spatialrecord, dpiapp,以及 dpigroup.
  • aiounifi --用于家庭助理UniFi集成的异步Python客户端。为DPI组、设备管理和v2 API路径提供了端点提示。
  • unifi网络服务器Docker镜像 Jacob Alberty——用于在Docker中运行临时测试控制器。

所有社区发现的端点都使用我们的自动探针和LLM探针管道与真实的v10.0.162独立控制器进行了验证。无法确认的端点被排除在外(参见 CLAUDE.md 对于完整的NOT_FOUND/UNCERTAIN表)。

该项目100%由人工智能生成

这个存储库中的每个文件都是由Claude(Anthropic)编写的。生成器、模板、测试套件、探测脚本、LLM发现工具、这个README——所有这些。没有人编写任何代码。

该项目专为AI到AI的使用而设计:AI代理生成服务器,AI代理通过MCP使用它来管理UniFi网络基础设施。人类也受到欢迎。

依赖项

Nix用户: nix run github:abl030/unifi-mcp --所有东西都捆绑在一起,不需要其他deps。

非Nix用户:

  • Python 3.11+
  • 紫外线 用于包管理
  • fastmcp、httpx、jinja2(由自动安装 uv sync)
  • Docker(仅用于运行测试套件)

许可证

麻省理工学院

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Unifi MCP (Abl030) 怎么安装?

在客户端按下面的安装命令接入:uv run python generate.py。装完在客户端配置里引用同一个包或端点。

Unifi MCP (Abl030) 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Unifi MCP (Abl030) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Unifi MCP (Abl030) 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

Unifi MCP (Abl030) 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Unifi MCP (Abl030) 能提供哪些能力?

资料显示约 294 个工具;能力标签包括 网络管理、自动化运维、Python、Claude、AI控制。具体工具清单以官方文档为准。

Unifi MCP (Abl030) 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Unifi MCP (Abl030) 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。