概述 unifi-mcp-server 是一个 Model Context Protocol（MCP）服务器，对外暴露 UniFi Network Controller API。它提供 74 个以上工具，用于管理 UniFi 设备、客户端、网络、WiFi、防火墙规则、QoS、备份、端口配置文件、RADIUS、访客门户以及多站点编排。
主要能力 设备管理：列出、监控、重启、定位、升级 UniFi 设备（AP、交换机、网关），并可强制下发配置。 网络配置：创建、更新、删除网络、VLAN、带 DHCP 的子网。 客户端管理：查询、阻断、解阻、重连客户端并获取分析数据。 WiFi/SSID 管理：创建支持 WPA2/WPA3 的无线网络、访客网络、VLAN 隔离。 防火墙规则：创建与管理防火墙规则、端口转发、流量过滤。 QoS 管理：流量优先级、带宽控制、流量整形。 备份与恢复：自动化调度、验证、下载/上传。 端口配置文件：交换机端口配置，支持 PoE、VLAN 干道、802.1X。 RADIUS 与访客门户：802.1X 认证、热点套餐。 多站点：跨站点聚合、分析、站点开通。 网络拓扑：完整的拓扑映射与可视化。 其他工具类别包括设备端口覆盖、DPI 统计等。
安装方式 通过 pip（推荐）： pip install unifi-mcp-server
通过 uv： uv pip install unifi-mcp-server
从源码安装： git clone https://github.com/enuno/unifi-mcp-server.git cd unifi-mcp-server pip install -e .
API 模式 本地网关 API（推荐）：完整功能支持，可获取实时数据并进行配置更改。需要设置环境变量 UNIFI_API_TYPE=local、UNIFI_LOCAL_HOST、UNIFI_USERNAME、UNIFI_PASSWORD、UNIFI_SITE。 Cloud Early Access API：以站点为中心的访问，仅具备受限的只读能力。需要设置 UNIFI_API_TYPE=cloud-ea、UNIFI_API_KEY，可选 UNIFI_SITE_MANAGER_ENABLED=true 用于多站点聚合。 Cloud V1 API：仅限聚合统计数据。需要设置 UNIFI_API_TYPE=cloud-v1、UNIFI_API_KEY。
传输模式 STDIO（默认）：面向本地 AI 客户端（Claude Desktop、Cursor）。设置 MCP_SERVER_TRANSPORT=stdio 后运行 unifi-mcp-server。 SSE（Server-Sent Events）：面向网络访问和 MCP 网关。设置 MCP_SERVER_TRANSPORT=sse、MCP_SERVER_PORT=3000 后运行 unifi-mcp-server。 HTTP / Streamable HTTP：设置 MCP_SERVER_TRANSPORT=http（或 streamable_http）、MCP_SERVER_PORT=3000 后运行 unifi-mcp-server。
配置示例 Claude Desktop：在 claude_desktop_config.json 中添加名为 unifi 的 mcpServers 条目，command 为 unifi-mcp-server，并在 env 中填入 UNIFI_API_TYPE、UNIFI_LOCAL_HOST、UNIFI_USERNAME、UNIFI_PASSWORD、UNIFI_SITE、MCP_SERVER_TRANSPORT。 MCP 网关（SSE 模式）：将 mcpServers 中 unifi 的 url 设置为 http://your-server-ip:3000/sse。 Docker Compose：使用镜像 ghcr.io/enuno/unifi-mcp-server:latest，配置相应环境变量与 3000 端口映射。
核心 MCP 工具 设备管理：list_devices、get_device、restart_device、locate_device、upgrade_device、force_provision_device。 客户端管理：list_clients、get_client、block_client、reconnect_client、get_client_stats。 网络配置：create_network、update_network、delete_network、list_networks。 WiFi/SSID 管理：create_ssid、update_ssid、delete_ssid、list_ssids。 防火墙规则：create_firewall_rule、update_firewall_rule、delete_firewall_rule、list_firewall_rules。 端口转发：create_port_forward、update_port_forward、delete_port_forward。 QoS 管理：create_qos_rule、update_qos_rule、delete_qos_rule、list_qos_rules。 端口配置文件：create_port_profile、update_port_profile、delete_port_profile、list_port_profiles。 设备端口覆盖：override_device_port、remove_device_port_override、get_device_port_config。 备份与恢复：create_backup、list_backups、download_backup、restore_backup、schedule_backup。 RADIUS 与访客门户：create_radius_account、update_radius_account、create_hotspot_package。 多站点管理：list_sites、get_site、create_site、get_cross_site_stats。 网络拓扑：get_network_topology、get_topology_map、get_device_connections、trace_route。 DPI 统计：get_dpi_stats、get_dpi_categories。
常见使用模式 完整网络搭建：先创建网络，再为该网络创建 WiFi，随后创建防火墙规则实现隔离，最后创建 QoS 规则限制带宽。 访客访问管理：创建访客网络、访客 SSID、热点套餐，并通过防火墙规则隔离访客网络。 交换机端口配置：为 VoIP 创建端口配置文件，应用到特定交换机端口，再验证配置。 监控与分析：遍历设备获取统计、获取客户端带宽使用、获取 DPI 分析、获取拓扑用于可视化。
故障排查 连接问题：检查环境变量、测试连通性、验证凭据。 SSL 证书错误：可设置 UNIFI_VERIFY_SSL=false（仅本地），或提供自定义 CA 包路径 UNIFI_SSL_CERT_PATH。 API 速率限制：Cloud-EA 为 100 请求/分钟，Cloud-V1 为 10,000 请求/分钟；高频操作建议使用本地 API，并在批量操作间添加延迟。 站点未找到：先列出所有站点，找到正确的站点 ID，再在环境中使用。 响应数据为空：云 API 可见性有限，可切换到本地 API，并核对站点参数。 传输模式问题：验证服务器监听端口、检查防火墙规则、测试端点，并在网关配置中使用正确 URL。
高级配置 环境变量参考：包括 API 配置（UNIFI_API_TYPE、UNIFI_API_KEY、UNIFI_LOCAL_HOST、UNIFI_USERNAME、UNIFI_PASSWORD、UNIFI_SITE、UNIFI_PORT、UNIFI_VERIFY_SSL、UNIFI_SSL_CERT_PATH）、传输配置（MCP_SERVER_TRANSPORT、MCP_SERVER_PORT、MCP_SERVER_HOST）以及可选功能（UNIFI_SITE_MANAGER_ENABLED）。
适用场景 适合需要在 MCP 客户端（如 Claude Desktop、Cursor）或 MCP 网关中集中管理 UniFi 网络环境的用户，尤其适用于设备与客户端运维、网络与 WiFi 配置、防火墙与 QoS 策略、备份恢复、访客认证以及多站点聚合管理等场景。
限制 不同 API 模式能力不同：本地网关 API 功能完整，Cloud Early Access API 以站点为中心且仅具备受限只读能力，Cloud V1 API 仅限聚合统计，云 API 存在速率限制且可见性有限。SSL 验证问题需通过关闭验证或提供 CA 包解决。若站点 ID 不匹配或站点参数错误，工具可能返回空数据。