UniFi MCP Server

通过 Model Context Protocol 实现完整的 UniFi Network 控制器管理

310 tools  •  16 categories  •  3 API layers  •  Network 5.x – 10.x

快速开始  •  工具覆盖  •  架构  •  配置

一个基于 Go 的 MCP server，为 AI 助手提供对 UniFi Network 控制器的深度、安全访问。专为 UniFi OS 设备（Dream Machine, Cloud Gateway）和 `unifi.ui.com` 云接口构建。 ## 为什么开发这个项目 通过自然语言管理 UniFi 网络意味着你的 AI 助手需要理解控制器 API 的每一个角落。本服务器暴露了涵盖完整 API 层面的 **310 tools** —— 从基本的设备列表到基于区域的防火墙策略排序，从热点凭证生成到 MC-LAG 域管理。 每一个变更操作都会经过一个 **confirm gate**，在执行前返回预览。助手能看到具体会发生什么变化，并在继续之前询问你。 ## 快速开始 添加到你的 MCP 客户端配置： ``` { "mcpServers": { "unifi": { "command": "ames-unifi-mcp", "env": { "UNIFI_HOST": "https://192.168.1.1", "UNIFI_API_KEY": "your-api-key-here", "UNIFI_SITE": "default", "UNIFI_VERIFY_SSL": "false" } } } } ``` 在 **Settings → Control Plane → Integrations** 生成 API key（需要 Network 9.1.105+）。对于旧版固件，请改用用户名/密码认证。 ## 工作原理 ### Lazy Mode（默认） 服务器不会向上下文窗口注入 310 个工具定义，而是仅暴露 **3 个元工具**： | Meta-Tool | 用途 | |-----------|---------| | `tool_index` | 浏览工具目录，可按类别筛选 | | `tool_execute` | 按名称运行任何工具并传入参数 | | `tool_batch` | 并行运行多个工具以提高效率 | 助手按需发现工具，保持上下文精简（约 200 个 token，而 eager mode 约为 30,000 个）。 ### Confirm Gate 每个写操作都需要显式确认。如果没有 `confirm: true`，工具会返回一个预览，显示*将要*发生什么： ``` You: "Restart the office access point" Assistant: Let me preview that first. → device_restart {"mac": "aa:bb:cc:dd:ee:ff"} ← Preview: This would restart "Office AP" (soft reboot). Confirm? You: "Yes" Assistant: → device_restart {"mac": "aa:bb:cc:dd:ee:ff", "confirm": true} ← Device restarting. ``` ### Permission Profiles 控制助手可以做什么： | Profile | 能力 | |---------|-------------| | **read-only** | 查询所有内容，不作任何更改 | | **standard** | 读取 + 安全变更（WLAN, clients, networks）。不包括 PoE 循环、系统重启或防火墙删除 | | **admin** | 完全访问权限，包括破坏性和系统级操作 | 权限被拒绝的工具仍会出现在 `tool_index` 中（标记为 `[PERMISSION DENIED]`），以便助手解释什么不可用及其原因。 ### Version Detection 启动时，服务器会查询控制器版本，并根据固件要求自动限制工具： | Feature | Minimum Version | |---------|----------------| | Legacy API (full) | 5.x+ | | Zone-Based Firewall | Network 9.0+ | | Integration API | Network 9.0+ | | API Key Authentication | Network 9.1.105+ | | DNS Policies, ACL Rules | Network 10.0+ | | Switch Stacks, LAGs, MC-LAGs | Network 10.0+ | | VPN Server/Tunnel CRUD | Network 10.1+ | 如果某个工具不在索引中，说明控制器固件版本过低，不支持该功能。 ## 工具覆盖 ### 16 个类别中的 310 个工具

**Devices** — 29 个工具 ``` device_list device_restart device_get device_adopt device_upgrade device_upgrade_all device_locate_on/off device_force_provision device_spectrum_scan device_rolling_upgrade_* device_migrate device_port_action device_list_v2 device_stats_latest device_unadopt device_pending_list ``` **Clients** — 15 个工具 ``` client_list_active client_block/unblock client_get client_reconnect client_forget client_sessions client_rename client_update client_list_v2 client_action ``` **Networks** — 10 个工具 ``` network_list network_create network_get network_update network_delete network_*_v2 (Integration API) ``` **Wireless (WLAN + WiFi)** — 12 个工具 ``` wlan_list wlan_create/update/delete wlan_enable wlan_disable wifi_broadcast_list/get/create/update/delete ``` **Firewall** — 23 个工具 ``` firewall_rule_* (legacy CRUD) firewall_group_* (address/port groups) firewall_zone_* (ZBF zones, 9.0+) firewall_policy_* (ZBF policies + ordering) ``` **ACL Rules** — 7 个工具 ``` acl_rule_list/get/create/update/delete acl_rule_ordering_get/set ``` **DNS Policies** — 5 个工具 ``` dns_policy_list/get/create/update/delete ``` **Traffic & QoS** — 15 个工具 ``` traffic_rule_* (v2 API rules) traffic_route_* (v2 API routes) traffic_matching_list_* (10.0+) ```

**VPN** — 10 个工具 ``` vpn_server_list/get/create/update/delete vpn_tunnel_list/get/create/update/delete ``` **Switching** — 15 个工具 ``` switching_stack_* (switch stacks) switching_lag_* (link aggregation) switching_mclag_* (MC-LAG domains) ``` **Stats & DPI** — 24 个工具 ``` stats_site_health stats_sysinfo stats_dashboard stats_report stats_speedtest_* stats_ips_events stats_rogueap stats_spectrumscan stats_dpi_site stats_dpi_client stats_dpi_apps stats_dpi_categories ``` **Events & Alarms** — 5 个工具 ``` event_list alarm_list alarm_count alarm_archive alarm_archive_all ``` **Hotspot & Guests** — 13 个工具 ``` hotspot_authorize/unauthorize_guest hotspot_create_voucher hotspot_extend hotspot_voucher_*_v2 (Integration API) hotspot_config hotspot_packages ``` **System & Settings** — 53 个工具 ``` system_reboot/poweroff system_settings system_backup_* system_firmware_* system_port_forward_* system_static_route_* system_usergroup_* system_portprofile_* system_dhcpoption_* system_radiusprofile_* system_tag_* system_led_toggle ``` **Cloud API** — 9 个工具 ``` cloud_host_list/get cloud_site_list cloud_device_list cloud_isp_metrics cloud_sdwan_* ``` **Admin & Misc** — 56 个工具 ``` admin_site_create/delete/rename admin_invite/revoke/grant/update poe_power_cycle syslog_query apgroup_* misc_rogueknown_* misc_scheduletask_* misc_hotspotop_* misc_dpigroup_* misc_cnt_resource ```

### API Layer Coverage 服务器覆盖所有三个 UniFi API 层： | API Layer | Path Prefix | Auth | Coverage | |-----------|-------------|------|----------| | **Legacy API** | `/api/s/{site}/...` | Session cookie | Full — stat, cmd, rest, set, get, upd, list, cnt, guest, dl | | **v2 API** | `/v2/api/site/{site}/...` | Session cookie | Full — traffic rules, traffic routes, AP groups, system logs | | **Integration API** | `/integration/v1/...` | API key or session | Full — devices, clients, networks, WiFi, firewall, VPN, switching, hotspot, DPI | | **Cloud Site Manager** | `api.ui.com/v1/...` | API key | Full — hosts, sites, devices, ISP metrics, SD-WAN | ## 配置 | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `UNIFI_HOST` | Yes | — | Controller URL (`https://192.168.1.1`) | | `UNIFI_API_KEY` | * | — | API key（推荐，需要 9.1.105+） | | `UNIFI_USERNAME` | * | — | 用户名（如果没有 API key） | | `UNIFI_PASSWORD` | * | — | 密码（如果没有 API key） | | `UNIFI_SITE` | No | `default` | 站点名称 | | `UNIFI_VERIFY_SSL` | No | `true` | `false` 用于自签名证书 | | `UNIFI_TOOL_MODE` | No | `lazy` | `lazy`（3 个元工具）或 `eager`（所有 310 个工具） | | `UNIFI_PERMISSION_PROFILE` | No | `standard` | `read-only`、`standard` 或 `admin` | _{* 需要提供 `UNIFI_API_KEY` 或同时提供 `UNIFI_USERNAME` + `UNIFI_PASSWORD`。} ### Authentication Methods **API Key**（推荐）— 在 Settings → Control Plane → Integrations 生成。支持 legacy 和 Integration API 端点。无会话管理开销。 **Username/Password** — 使用会话 cookie，过期时自动重新登录。服务器包含单次重登录机制，可防止批量操作同时遇到会话超时时出现的惊群效应。 ## 架构 ``` cmd/ames-unifi-mcp/main.go Entry point, server wiring internal/ config/ Environment config loading client/ HTTP client - Session auth with auto re-login (single-flight) - API key auth (X-API-Key header) - CSRF token management (thread-safe) - Retry with backoff (429, 5xx) - Legacy envelope parsing (meta.rc/data) - Raw response passthrough (Integration/v2 APIs) version/ Controller version detection permissions/ Permission profiles tools/ tool.go Tool interface registry.go Tool registry with version/permission gating confirm.go Confirm gate (dry-run preview pattern) metatools.go tool_index, tool_execute, tool_batch core/ Core tool implementations devices.go clients.go networks.go wlan.go wifi.go firewall.go acl.go dns.go traffic.go wan.go switching.go stats.go events.go system.go extended/ Extended tool implementations poe.go hotspot.go cloud.go admin.go syslog.go apgroups.go misc.go ``` ### 关键设计决策 **默认 Lazy mode。** LLM 直接调用 310 个工具会浪费上下文并混淆工具选择。3-meta-tool 模式让助手按需发现工具，通常工具定义只需使用 < 200 个 token 的上下文。 **所有变更操作都有 Confirm gate。** 不依赖 MCP 客户端来防止意外操作，每个变更工具默认返回预览。`confirm: true` 参数是显式选择加入。这已融入工具 schema —— LLM 将其视为必需步骤，而不是可选标志。 **注册时进行版本控制。** 针对新 API 功能的工具不会被隐藏或报错 —— 如果控制器版本过旧，它们根本不会注册。工具索引只显示实际可用的内容。 **带可见性的权限控制。** 被拒绝的工具会带有 `[PERMISSION DENIED]` 后缀出现在索引中。这让助手可以向用户解释为什么某些功能不可用，而不是返回隐晦的“unknown tool”错误。 ## 构建 ``` go build -o ames-unifi-mcp ./cmd/ames-unifi-mcp/ ``` ### 交叉编译 ``` # Linux ARM64 (e.g., Raspberry Pi, Docker on NAS) GOOS=linux GOARCH=arm64 go build -o ames-unifi-mcp ./cmd/ames-unifi-mcp/ # Linux AMD64 GOOS=linux GOARCH=amd64 go build -o ames-unifi-mcp ./cmd/ames-unifi-mcp/ ``` ### 运行测试 ``` go test ./... ``` ## 常见操作 以下是自然语言网络管理的示例： **“我的网络状况如何？”** ``` → tool_batch: stats_site_health + client_list_active + alarm_count ← WAN: healthy, 47 clients connected, 0 active alarms ``` **“阻止那个可疑设备”** ``` → client_get {"mac": "aa:bb:cc:dd:ee:ff"} ← Device "Unknown-IoT" on VLAN 30, 2.3 GB today → client_block {"mac": "aa:bb:cc:dd:ee:ff"} ← Preview: Would block Unknown-IoT. Confirm? → client_block {"mac": "aa:bb:cc:dd:ee:ff", "confirm": true} ← Blocked. ``` **“创建一个 24 小时的访客凭证”** ``` → hotspot_create_voucher {"expire_minutes": 1440, "quota": 1} ← Preview: Would create 1 single-use voucher, 24h validity. Confirm? → hotspot_create_voucher {"expire_minutes": 1440, "quota": 1, "confirm": true} ← Voucher created: 83927-10458 ``` **“哪些 AP 还在用旧固件？”** ``` → device_list_basic ← 12 devices. Filtering by upgrade_available... - Lobby AP (U6-Pro) — current: 6.6.55, available: 7.0.83 - Garage AP (U6-Lite) — current: 6.6.55, available: 7.0.83 ``` ## 许可证 MIT — 与 Ubiquiti Inc. 无关。

_{由 Vermont 的 Oliver Ames 构建 • GitHub • LinkedIn • Bluesky}

标签：AI助手, API, CISA项目, Docker 部署, Dream Machine, EVTX分析, Go, IT基础设施, MCP服务器, Ruby工具, Ubiquiti, UniFi, UniFi OS, VPN, WiFi管理, 云管理, 交换机管理, 人工智能, 企业网络, 局域网, 工具集, 日志审计, 模型上下文协议, 状态监控, 用户模式Hook绕过, 网络安全, 网络控制器, 网络自动化, 网络设备管理, 网络运维, 网络连接监控, 网络配置, 防火墙, 隐私保护