Groupthink-dev/ubiquiti-unifi-blade-mcp

# ubiquiti-unifi-blade-mcp  一个为 AI agent 提供对 Ubiquiti UniFi 网络控制器结构化访问权限的 MCP 服务器。为 [Model Context Protocol](https://modelcontextprotocol.io) 而构建，以安全可见性和 token 效率为首要设计目标。 ## 为什么需要这个项目 UniFi 控制器在其基于 cookie 的身份验证（带有 CSRF token 和可选的 2FA）背后，暴露了一个丰富但未公开文档的 REST API。[aiounifi](https://github.com/Kane610/aiounifi) 库（采用 MIT 许可证，为 Home Assistant 集成提供支持）处理了所有的协议复杂性——例如 UniFi OS 与传统控制器的检测、TOTP 2FA、websocket 事件等。此 MCP 使用自动化 agent 所需的安全防护机制对其进行了封装： - **安全优先的工具集** —— 包含 30 个专注于网络安全 agent 实际需求的工具：设备健康状况、客户端可见性、防火墙状态、流量规则、DPI 限制、端口转发、network/VLAN 以及 Integration-API 资源。而不是为所有可能的配置更改提供 161 个工具。 - **Token 高效输出** —— 紧凑的管道分隔格式。一个拥有 30 台设备的网络大约只需每台设备 50 个 token。客户端列表一目了然地显示信号强度、体验评分和屏蔽状态。 - **写入门控变更** —— 客户端屏蔽、WLAN 切换、设备重启和流量路由更改需要通过 `UNIFI_WRITE_ENABLED=true` 明确授权。破坏性操作（屏蔽、重启）还需要每次调用时设置 `confirm=true`。 - **多控制器** —— 通过单个 MCP 实例管理家庭和办公网络。每个控制器都通过独立的会话进行身份验证。 ## 与其他 UniFi MCP 的区别 | | ubiquiti-unifi-blade-mcp | sirkirby/unifi-mcp | enuno/unifi-mcp-server | |---|---|---|---| | **侧重点** | 监控 + 安全 + Integration-API 资源管理（30 个工具） | 全面管理（161 个工具） | 全面管理（74 个工具） | | **设计目标** | LLM agent（token 高效） | Claude Code（延迟加载） | 通用 MCP 客户端 | | **多控制器** | 原生支持（环境变量配置） | 单控制器 | 多模式（本地/云端） | | **写入安全** | 双重门控（环境变量 + 确认） | 预览后确认 | 权限模型 | | **2FA 支持** | 通过 aiounifi 支持 TOTP | 支持 TOTP | API key 选项 | | **输出** | 管道分隔，紧凑 | 完整 JSON | 完整 JSON | | **市场** | Sidereal 认证 | Claude Code 插件 | 独立运行 | 当你需要进行 agent 驱动的监控和安全防护时，请使用此 blade-MCP。当你需要进行全面的网络配置管理时，请使用 sirkirby/unifi-mcp（作为社区列表在 Sidereal 市场中提供）。 ## 快速开始 ``` # 安装 uv pip install -e . # 配置（监控工具 — username/password） export UNIFI_HOST="192.168.1.1" export UNIFI_USERNAME="admin" export UNIFI_PASSWORD="your-password" export UNIFI_VERIFY_SSL="false" # Common for self-signed certs # 配置（network/VLAN 工具 — Integration API key） # 在 UniFi Network → Settings → Control Plane → Integrations 中生成 export UNIFI_API_KEY="your-x-api-key" # 运行 ubiquiti-unifi-blade-mcp ``` ## 身份验证：两种模式 | 模式 | 环境变量 | 驱动 | Endpoint | 支持状态 | |------|-----|--------|----------|----------------| | **API key** | `UNIFI_API_KEY` (`X-API-KEY`) | Networks/VLANs + 所有 `unifi_resource_*` 工具（WiFi、防火墙、ACL、DNS、凭证等） | 官方 **Integration API** (`/proxy/network/integration/v1`) — 无状态 | ✅ 由 Ubiquiti **官方支持** | | **Session** | `UNIFI_USERNAME` + `UNIFI_PASSWORD`（+ 可选的 `UNIFI_TOTP_SECRET`） | 监控/安全读取工具（设备、客户端、防火墙视图、WLAN、DPI、流量、端口转发） | 通过 `aiounifi` 的旧版私有控制器 API (cookie/CSRF) | ⚠️ **非官方 / 不受支持** | 可以设置其中一个或同时设置两者。Integration-API 工具需要 API key（这是唯一支持写入的路径）；监控读取工具需要用户名/密码。 ### 生成 API key API key 是**在 UniFi 控制台 UI 上**生成的（而不是通过此 MCP）。Ubiquiti 经常重命名设置树，因此不同版本之间的确切措辞会有所变化。 **截至 UniFi Network 10.4（2026 年 6 月）：** 1. 打开 UniFi Network 应用程序（本地控制台 UI 位于 `https://`，或通过 `unifi.ui.com` → 你的控制台）。 2. **Settings**（齿轮图标）→ **Control Plane** → **Integrations**。 *(在某些 10.x 版本中，这显示为 Settings → **System** → **Integrations**，或者 **Admins & Users** → **API Keys** —— 如果没有“Control Plane”，请在 Settings → System 下的任何地方寻找“Integrations”或“API”。)* 3. 点击 **Create API Key**，为其命名（例如 `blade-mcp`），将过期时间设置为 **Never Expires**，然后点击 **Create**。  4. **立即复制密钥** —— 它**只会显示一次**。  5. 将密钥存储在你的密钥管理器中，并将其设置为 `UNIFI_API_KEY`。 ### 为 session (监控) 工具创建专用的本地管理员 监控工具通过用户名/密码进行身份验证。与其使用你的个人超级管理员账户，不如创建仅限控制器的**专用本地管理员**。受写入门控的变更工具（屏蔽客户端、重启设备、切换 WLAN）需要比 Viewer 更高的角色，因此建议创建两个账户： | 账户 | 用户名 | 角色 | 使用场景 | |---------|----------|------|----------| | `Ro MCP` | `mcp-ro` | Viewer | `UNIFI_WRITE_ENABLED` 未设置 / 只读 agent | | `Rw MCP` | `mcp-rw` | Network Admin (或 Full Access) | `UNIFI_WRITE_ENABLED=true` | **步骤（对每个账户重复操作）：** 1. **Settings** → **Admins & Users** → **Admin Permissions** → **Create New**。 2. 将 **First Name** / **Last Name** 设置为 `Ro MCP` 或 `Rw MCP`。 3. 勾选 **Restrict to Local Access Only** —— 防止该账户在 `unifi.ui.com` 进行身份验证。 4. 勾选 **Use a Predefined Role** 并选择适当的角色（只读选择 Viewer；读写选择 Network Admin 或 Full Access）。 5. 设置强密码并点击 **Create**。  6. 在管理员列表中验证创建的配置文件 —— 确认 **Restrict to Local Access Only** 已开启并且角色正确。  7. 将 `UNIFI_USERNAME` 和 `UNIFI_PASSWORD` 设置为该账户的凭证。默认使用 `mcp-ro` 凭证；仅在设置了 `UNIFI_WRITE_ENABLED=true` 的会话中切换为 `mcp-rw`。 ## 30 个工具，7 个类别 ### 信息与站点 (3 个工具) | 工具 | 目的 | Token 成本 | |------|---------|------------| | `unifi_controllers` | 列出已配置的控制台（名称、主机、默认值） —— 无需网络；填充 `controller` 选择器 | ~15 | | `unifi_info` | 健康检查 —— 控制器版本、主机名、设备/客户端数量、写入门控（省略 `controller` 时为所有控制台） | ~60 | | `unifi_sites` | 列出控制器上的站点 | ~20/站点 | ### Networks 与 VLANs (3 个读取工具 —— 需要 `UNIFI_API_KEY`) | 工具 | 目的 | Token 成本 | |------|---------|------------| | `unifi_networks` | 列出 networks/VLANs —— 名称、VLAN id、启用状态、用途、子网 | ~25/网络 | | `unifi_network` | 完整详情 —— VLAN id、子网、网关、用途 | ~60 | | `unifi_zones` | 列出 `unifi_create_network` 使用的网络/防火墙区域和 ID | ~20/区域 | ### 设备 (2 个工具) —— ⚠️ 非官方 API | 工具 | 目的 | Token 成本 | |------|---------|------------| | `unifi_devices` | 列出 AP、交换机、网关 —— 型号、状态、客户端、正常运行时间、固件 | ~50/设备 | | `unifi_device` | 完整详情 —— 带有 PoE 的端口表、固件、升级状态 | ~150 | ### 客户端 (2 个工具) —— ⚠️ 非官方 API | 工具 | 目的 | Token 成本 | |------|---------|------------| | `unifi_clients` | 已连接的客户端 —— 名称、IP、SSID、信号、体验、屏蔽状态 | ~40/客户端 | | `unifi_client` | 完整详情 —— TX/RX、供应商 (OUI)、AP 关联 | ~120 | ### 防火墙与安全 (5 个工具) —— ⚠️ 非官方 API（只读） 这些读取视图运行在**非官方**私有 API 之上（请参阅上面的身份验证警告）。对于*受管理*的防火墙，请使用官方 `unifi_resource_*` 工具配合 `firewall_policies` / `firewall_zones` / `acl_rules`。 | 工具 | 目的 | Token 成本 | |------|---------|------------| | `unifi_firewall` | 防火墙策略 —— 名称、操作、启用/禁用 | ~30/策略 | | `unifi_traffic_routes` | 流量路由 —— 描述、启用/禁用、目标 | ~25/路由 | | `unifi_traffic_rules` | 流量规则 —— 描述、操作、启用/禁用 | ~25/规则 | | `unifi_port_forwards` | 端口转发 —— 名称、协议、外部 → 内部 | ~30/转发 | | `unifi_dpi` | DPI 限制组和应用程序 | ~20/项 | ### 写入操作 (10 个工具，受门控) 前六个运行在**非官方**私有 API 上 (⚠️)；三个 `*_network` 工具使用**官方** Integration API (✅)。 | 工具 | 门控 | API | 目的 | |------|------|-----|---------| | `unifi_block_client` | write + confirm | ⚠️ 非官方 | 屏蔽网络中的客户端 | | `unifi_unblock_client` | write | ⚠️ 非官方 | 取消屏蔽之前被屏蔽的客户端 | | `unifi_reconnect_client` | write | ⚠️ 非官方 | 强制无线客户端重新连接 | | `unifi_toggle_wlan` | write | ⚠️ 非官方 | 启用或禁用 SSID | | `unifi_toggle_traffic_route` | write | ⚠️ 非官方 | 启用或禁用流量路由 | | `unifi_restart_device` | write + confirm | ⚠️ 非官方 | 重启 AP、交换机或网关 | | `unifi_create_network` | write + confirm + API key | ✅ 官方 | 创建 network/VLAN；接受 `zone_id` 或 `zone_name`，否则仅在明确的情况下自动选择默认/内部区域 | | `unifi_update_network` | write + confirm + API key | ✅ 官方 | 更新 network/VLAN（提供的字段） | | `unifi_delete_network` | write + confirm + API key | ✅ 官方 | 删除 network/VLAN | ### Integration-API 资源 (5 个通用工具 —— 需要 `UNIFI_API_KEY`) 除了专用的网络工具外，通用的 CRUD 接口还涵盖了官方 UniFi **Integration API** 的其余资源。写入根据控制台上的 schema 获取原始 JSON `body`；读取/列表适用于所有资源。 | 工具 | 门控 | 目的 | |------|------|---------| | `unifi_resource_list` | API key | 列出以下任意资源的项 | | `unifi_resource_get` | API key | 某一项的完整详情 | | `unifi_resource_create` | write + confirm + API key | 创建项（原始 `body`） | | `unifi_resource_update` | write + confirm + API key | 更新 (PUT) 项（原始 `body`） | | `unifi_resource_delete` | write + confirm + API key | 删除项 | **`resource` 值** → Integration-API 路径： | 资源 | 路径/proxy/network/integration/v1/sites/{id}/…`) | 可写入 | |----------|------|:---:| | `networks` | `networks` | ✅ | | `wifi` | `wifi/broadcasts` | ✅ | | `firewall_policies` | `firewall/policies` | ✅ | | `firewall_zones` | `firewall/zones` | ✅ | | `acl_rules` | `acl-rules` | ✅ | | `dns_policies` | `dns/policies` | ✅ | | `traffic_matching_lists` | `traffic-matching-lists` | ✅ | | `vouchers` | `hotspot/vouchers` | ✅ | | `wan_interfaces` | `wans` | 只读 | | `radius_profiles` | `radius/profiles` | 只读 | | `vpn_servers` | `vpn/servers` | 只读 | | `vpn_tunnels` | `vpn/site-to-site-tunnels` | 只读 | | `device_tags` | `device-tags` | 只读 | ### 输出格式 ``` Office AP | uap | model=U6-Pro | ip=192.168.1.10 | connected | clients=12 | up=10d0h | mac=aa:bb:cc:dd:ee:01 Core Switch | usw | model=USW-Pro-48-PoE | ip=192.168.1.2 | connected | up=30d0h | UPGRADE_AVAILABLE | mac=aa:bb:cc:dd:ee:02 Gateway | ugw | model=UDM-Pro | ip=192.168.1.1 | connected | up=60d0h | mac=aa:bb:cc:dd:ee:03 ``` ``` MacBook Pro | ip=192.168.1.100 | ssid=HomeNet | rssi=-55 | exp=98% | up=12h0m | mac=11:22:33:44:55:01 NAS | ip=192.168.1.50 | wired | exp=100% | up=30d0h | mac=11:22:33:44:55:02 Unknown Device | ip=192.168.1.200 | ssid=IoT-Net | rssi=-72 | exp=65% | BLOCKED | mac=11:22:33:44:55:03 ``` ## 多控制器支持 ``` export UNIFI_CONTROLLERS="home,office" export UNIFI_HOME_HOST="192.168.1.1" export UNIFI_HOME_USERNAME="admin" export UNIFI_HOME_PASSWORD="home-password" export UNIFI_OFFICE_HOST="10.0.0.1" export UNIFI_OFFICE_USERNAME="admin" export UNIFI_OFFICE_PASSWORD="office-password" ``` 调用 `unifi_controllers` 列出已配置的控制台，然后将例如 `controller="office"` 传递给任何工具。选择规则： - **读取工具** —— 省略 `controller` 以使用默认（第一个配置的）控制台。 - **调查工具** (`unifi_info`, `unifi_controllers`) —— 省略 `controller` 以覆盖**所有**控制台。 - **写入工具** —— 当配置了多个控制台时，`controller` 是**必填的**；省略控制器将被拒绝，而不是静默地以默认控制器为目标。这可以防止变更（屏蔽、重启、删除网络）落到错误的网络上。单控制台设置则保持符合人体工程学的省略操作。 ## 安全模型 | 层级 | 机制 | |-------|-----------| | **写入门控** | 任何变更都需要 `UNIFI_WRITE_ENABLED=true` | | **多控制台写入范围界定** | 配置了 >1 个控制台时，写入工具需要显式的 `controller=` —— 省略控制器将被拒绝，绝不静默使用默认值 (DD-343 连接范围界定) | | **破坏性确认** | `unifi_block_client`、`unifi_restart_device` 以及所有 `unifi_*_network` 写入工具都需要 `confirm=true` | | **凭证清洗** | 从错误信息中剔除密码、cookie、CSRF token、`X-API-KEY`、session ID | | **控制器 API key** | `UNIFI_API_KEY` (`X-API-KEY`) —— 用于 network/VLAN 工具的具有作用域的 Integration API key | | **HTTP 传输身份验证** | `UNIFI_MCP_API_TOKEN` bearer token；没有它，HTTP 传输**拒绝启动**（仅限 loopback，stdio 是默认值） | | **会话隔离** | 每个控制器独立进行身份验证 | | **可配置 SSL** | 对于具有正确证书的环境使用 `UNIFI_VERIFY_SSL=true` | | **2FA 支持** | 通过 `UNIFI_TOTP_SECRET` 支持 TOTP（base32 编码） | ## Sidereal 集成 ``` { "mcpServers": { "unifi": { "type": "stdio", "command": "uv", "args": ["--directory", "~/src/ubiquiti-unifi-blade-mcp", "run", "ubiquiti-unifi-blade-mcp"], "env": { "UNIFI_HOST": "192.168.1.1", "UNIFI_USERNAME": "admin", "UNIFI_PASSWORD": "...", "UNIFI_VERIFY_SSL": "false", "UNIFI_WRITE_ENABLED": "false" } } } } ``` ### Webhook 触发模式 - **设备状态更改** —— `unifi_devices` 返回状态（已连接/已断开/正在升级），从而能够对 AP/交换机故障发出警报 - **新/未知客户端** —— 带有屏蔽状态的 `unifi_clients`，用于入侵检测工作流 - **固件可用性** —— `unifi_devices` 标记 `UPGRADE_AVAILABLE` 以进行维护计划 - **防火墙审计** —— `unifi_firewall` + `unifi_port_forwards` 用于定期的安全态势检查 ## 开发 ``` make install-dev # Install with dev + test dependencies make test # Unit tests (mocked, no controller needed) make check # Lint + format + type-check make run # Start MCP server (stdio) ``` ### 架构 ``` src/ubiquiti_unifi_blade_mcp/ ├── server.py — FastMCP server, 30 @mcp.tool decorators ├── client.py — UniFiClient: aiounifi session auth + Integration API (X-API-KEY) generic resource layer, multi-controller, credential scrubbing ├── formatters.py — Token-efficient output (pipe-delimited, null omission, human units) ├── models.py — Controller config, auth modes, write gate, network payload builder └── auth.py — Bearer token middleware for HTTP transport ``` 使用 [FastMCP 2.0](https://github.com/jlowin/fastmcp) 和 [aiounifi](https://github.com/Kane610/aiounifi) 构建。 ## 鸣谢 - [Kane610/aiounifi](https://github.com/Kane610/aiounifi) —— 为此项目和 Home Assistant 集成提供支持的异步 UniFi 库 - [sirkirby/unifi-mcp](https://github.com/sirkirby/unifi-mcp) —— 用于全面网络管理的综合 UniFi MCP（作为社区列表提供） ## 许可证 MIT

标签：MCP, Ubiquiti UniFi, 运维工具, 逆向工具