UniFi MCP

UniFi + AI - 适用于 ChatGPT、Claude、GitHub Copilot、Microsoft 365 Copilot、Gemini，以及任何支持 MCP 的 Agent

非官方。由社区构建的 Claude Code Skill 和 UniFi API MCP 服务。与 Ubiquiti Inc. 无关联，未获其认可或赞助。

_{完整技能页面 - 安装、使用成果、安全模型。}

支持 UniFi Network API 的所有操作，还具备其他 UniFi 工具都没有的偏差检测、拓扑分析和规则预测功能。可与您已在使用的 AI 配合使用——ChatGPT（Plus/Pro+，在此连接器重新发布前暂停；参见 mcp-install.md）、Claude Desktop、Codex、Claude Code、Claude Cowork 和 GitHub Copilot——还可通过远程方式使用 Microsoft 365 Copilot / Copilot Studio 和 Google Gemini。免费、开源，可在您的笔记本电脑上运行。专为 MSP 所有者打造。无需编写代码。

适用于您的 Agent

安全提示（此连接器重新发布前适用）。 请勿运行 HTTP 模式 （--transport http），即使是在 localhost 上也不行。此版本没有密码， 会监听所有网络接口，而且早于浏览器重绑定防护机制，因此您打开的网页可以访问它。 MCP 工具还可以使用您的凭据进行更改。请使用默认的 stdio 传输方式。如果您为 远程 Agent 设置了隧道，请将其关闭。修复即将推出。

MSP 所有者实际使用的六种 Agent（可自行安装，即刻可用）：

您的 AI Agent	如何安装 UniFi 技能
Claude Desktop	运行安装程序，然后前往 Settings > Extensions 注册 unifi-network-mcp（无需编辑 JSON）。
ChatGPT（付费计划）	在此连接器重新发布前暂停：ChatGPT 需要 HTTP 模式，而此版本的该模式不要求密码、会监听所有网络接口，且您打开的网页可以访问它。参见 mcp-install.md 中的安全提示。
Codex CLI	粘贴下方的安装提示词。
Claude Code	粘贴下方的安装提示词。
Claude Cowork	粘贴下方的安装提示词。
GitHub Copilot（VS Code）	运行安装程序，在 mcp.json 的 servers 键下添加 unifi-network-mcp，然后选择 Agent 模式。

ChatGPT 需要远程 HTTPS 服务，这意味着需要使用此连接器的 HTTP 模式；该模式在连接器重新发布前暂停：此版本的该模式不要求密码、会监听所有网络接口，且您打开的网页可以访问它。参见 mcp-install.md 中的安全提示。

同样适用于 Microsoft 和 Google 技术栈

安装量很大，但先如实提醒：这些属于远程／企业路径，并非你刚刚安装的本地二进制文件。

Agent	所需内容
Microsoft 365 Copilot / Copilot Studio	暂停使用，直到重新打包此连接器：Copilot Studio 需要使用 HTTP 模式，而在此构建版本中，该模式不需要密码，会监听所有网络接口，并且可被你打开的网页访问。请参阅 mcp-install.md 中的安全说明。
Google Gemini	Gemini CLI 是本地运行的，与 Claude Code 相同。Gemini 应用是远程的，需要使用与 ChatGPT 相同的、目前已暂停的 HTTP 模式。请参阅 mcp-install.md。

原生支持技能的 Agent（同样适用）： Hermes 和 OpenClaw 会直接读取此技能的 SKILL.md，同时支持 MCP；请参阅下文的安装章节。也可通过 MCP 与 Cursor、Windsurf、Cline、Continue.dev 和 Zed 搭配使用。各工具的完整接入说明：docs/which-agent.md。

要运行多个 Agent？ 只需一条命令，即可为所有 51+ 个受支持的 Agent 安装：npx skills add Servosity/msp-skills@latest（需要 Node.js，然后运行相应技能的安装程序来安装 CLI／MCP 二进制文件）。请参阅 docs/which-agent.md。

60 秒内完成安装

Claude Desktop 最快捷方式 - 一键安装 .mcpb

Claude Desktop 安装包： .mcpb 可在 macOS（Intel 和 Apple Silicon）、Windows x64 和 Linux x64 上启动。每个工具都会调用配套的 unifi-network-cli。从 2026-09-18 起发布的版本会将该 CLI 一并打包；更早的安装包只包含 MCP 服务，因此如果你的安装包中没有配套 CLI，请先运行下方的路径 A 或路径 B 安装程序（或者将 UNIFI_CLI_PATH 设为现有二进制文件的路径）。详情：#331。

下载 UniFi MCP (.mcpb) - 然后打开 Claude Desktop > 设置 > 扩展并选择该文件。一键完成，无需 JSON 或命令行。（在 发布页面浏览所有 UniFi 版本。）

更喜欢 Claude Code 插件？只需添加一次市场，然后安装即可 - 无需列出目录，立即生效：

/plugin marketplace add Servosity/msp-skills
/plugin install unifi-network@msp-skills

路径 A - 向 AI Agent 粘贴一条提示词（推荐）

将以下内容复制到 Claude Code、Codex CLI 或 Claude Cowork：

在此 Agent 工作区中，从 Servosity/msp-skills 安装 UniFi Skill 和 MCP 服务。如果此工作区使用 POSIX shell（macOS、Linux、WSL 或 Bash），运行 bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/unifi-network/install.sh)。如果使用 Windows PowerShell，运行 iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/unifi-network/install.ps1 | iex。然后按照 README 进行身份验证，并运行 unifi-network-cli --help 进行探索。

任何能够运行 shell 的 Agent 都可以使用相同的提示词。

路径 B - 自行运行安装程序

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/unifi-network/install.ps1 | iex

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/unifi-network/install.sh)

安装程序会将 unifi-network-cli（CLI）和 unifi-network-mcp（MCP 服务）都放入用户的 bin 路径。Claude Code、Codex 和 Cowork 会通过此目录中的 SKILL.md 发现该技能。

验证：

unifi-network-cli --version

升级到最新版本

安装程序始终获取当前版本；重新运行即可升级：

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/unifi-network/install.sh)

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/unifi-network/install.ps1 | iex

Claude Desktop .mcpb 用户：下载最新的 .mcpb（见本节顶部），然后在设置 > 扩展中重新选择。Claude Code 插件用户：/plugin update unifi-network@msp-skills。

添加到 Claude Desktop、GitHub Copilot、Gemini CLI、Microsoft 365 Copilot 或其他 MCP 客户端

安装程序运行后，请参阅 mcp-install.md 和 docs/which-agent.md，了解各 Agent 的连接配置——每个 Agent 都有单独的章节，其中包括 GitHub Copilot 的 servers 键，以及 Microsoft 365 Copilot / Copilot Studio 的远程接入方式。Claude Desktop 的 Settings > Extensions 面板是最简单的方式；对于偏好编辑 JSON 的用户，mcp-install.md 中记录了 MCP 配置块。

安装到 Hermes

在 Hermes CLI 中：

hermes skills install servosity/msp-skills/skills/unifi-network --force

在 Hermes 聊天会话中：

/skills install servosity/msp-skills/skills/unifi-network --force

Hermes 原生支持 MCP，因此也可以直接使用 unifi-network-mcp 服务——安装方式和环境变量相同。

安装到 OpenClaw

告诉你的 OpenClaw Agent（复制以下内容）：

从 https://github.com/servosity/msp-skills/tree/main/skills/unifi-network 安装 unifi-network 技能。该技能定义了如何通过 openclaw: frontmatter 块安装其必需的 CLI（unifi-network-cli）。

OpenClaw 尚未普遍开放；frontmatter 配置已预先提供，OpenClaw 一经发布便会启用。

身份验证

设置 CLI 所需的凭据（从你的 UniFi 门户获取）：

UNIFI_API_KEY=<value> UNIFI_GATEWAY_HOST=<value> unifi-network-cli doctor

doctor 会检查配置、路径和网关可达性，然后通过一次经过身份验证的读取来验证密钥本身：它会报告 valid、rejected (HTTP 401)、scope-limited (HTTP 403)，如果探测未能到达可检查密钥的端点，则报告 not verified。即使凭据遭拒，它也会以状态码 0 退出，因此脚本应添加 --fail-on error。

此技能的功能

MSP 经常提出的问题	命令
自上次检查以来，此站点的配置发生了哪些变化？	unifi-network-cli drift --site default --json
本周有哪些设备和客户端加入了网络？	unifi-network-cli newcomer --since 7d --json
添加硬件前，交换机端口和 PoE 容量是否充足？	unifi-network-cli port-audit --site default
哪条防火墙策略会匹配来自此主机的流量？	unifi-network-cli rule-predict --src 10.0.3.50 --dst 10.0.0.1
哪些客户端连接在哪些设备后面？	unifi-network-cli topology --site default
此站点配置了哪些防火墙策略？	unifi-network-cli sites firewall get-policies <siteId> --all
谁在使用访客网络？哪些访客券仍有效？	unifi-network-cli guest report --site default
列出站点上所有已纳管的设备	unifi-network-cli sites devices get-adopted-overview-page <siteId> --all

请先运行 unifi-network-cli sync——drift、newcomer、topology、guest report 和 rule-predict 都基于本地镜像计算，而 port-audit 需要先同步设备列表， 才能获取端口详情。对于分页读取，请传入 --all：这些命令默认使用 --limit 25（访客券为 100），且不会发出截断警告。这也适用于 countries、pending-devices 和 dpi ...，不只是 sites ... 子树。

完整功能包含 137 个命令；其中几乎所有命令都位于 sites ... 下。运行 unifi-network-cli sites --help 可列出 14 个资源组，然后运行 unifi-network-cli sites <group> --help 查看每个组的命令。guide.md 介绍了安装、身份验证和主要命令。有关 AI Agent 操作规范（--agent、--dry-run，以及何时应在执行变更前确认），请参阅 AGENTS.md。

特别之处

大多数 UniFi 集成和 MCP 服务都会将每个问题转发为一次实时 API 调用。查询单条记录时，这样没问题。但只要你问到任何历史问题——“这个站点从周五以来有什么变化？”“这个接入点是新的吗？”——它们就无能为力，因为 UniFi Network 集成 API 没有配置版本管理功能，也没有审计日志端点。根本没有历史记录可供转发查询。

这个技能会将 UniFi 数据同步到一个带有全文搜索功能的本地 SQLite 镜像中，并在此基础上维护自己的快照。这正是它能回答历史问题的原因：drift 会将站点的网络、防火墙、WiFi 和 DNS 配置与上次运行时捕获的状态进行比较，而 newcomer 会为每台设备和每个客户端保存首次发现记录，让新硬件能够基于真实基线显现出来。topology 和 guest report 则整合了 API 只会分开返回的数据——topology 会将每个已同步的客户端嵌套在其所连接的设备下，而 guest report 会在同一份输出中列出站点当前有效的热点凭证和已连接的访客客户端，无需在三个控制台界面间切换。这些都是无状态 API 封装器做不到的工作，因为状态从未保存在其他地方。

解决的痛点

UniFi 设备广泛应用于小型企业网络，而运营者总是向它询问一件它无法提供的东西：历史记录。Network 集成 API 没有配置版本管理功能，也没有审计日志端点，因此，对于“这个站点发生了什么变化，何时发生的？”，根本无从查询。多年来，Ubiquiti Community 一直有人针对这一问题提出功能请求，例如标题为 UniFi Change Logs or Change Control options?、UniFi audit/change logs supported? 和 Audit log of recent changes 的讨论帖。

同样的基线缺失问题还体现在另外两方面。对于客户端，完全没有首次发现记录（API 只提供当前会话的 connectedAt），因此无法区分今天早上刚出现的笔记本电脑和已经存在一年的笔记本电脑；对于设备，虽然有 adoptedAt，但它只出现在逐台设备的详情请求中，从不会出现在你实际扫描的列表中。而且，任何列表响应中都不会包含各端口的接口数据——只有逐台设备的详情请求才有——所以要回答“哪些端口空闲，哪些已经在为 PoE 供电？”，就得逐个打开站点上的每台交换机。

• unifi-network-cli drift --site default --json - 将站点配置与此命令上次运行时捕获的快照进行比较，然后更新快照。它会自行维护历史记录，正是因为 API 没有历史记录。
• unifi-network-cli newcomer --since 7d --json - 为每台设备和每个客户端保存首次发现记录，让新硬件基于基线显现，而不是只显示一份平铺列表。
• unifi-network-cli port-audit --site default --json - 显示每台交换设备或网关设备各端口的链路状态和 PoE 状态。不使用 --json 时，终端会为每台设备打印一行摘要：N up / M down, PoE active on K port(s)。
• unifi-network-cli rule-predict --src 10.0.3.50 --dst 10.0.0.1 - 按照网关自身的首条匹配优先顺序检查已同步的策略，并报告可能匹配的规则；无法解析的部分会标记为不确定，而不是猜测。请传入主机 IP：CIDR 的掩码会被忽略，只会测试你输入的地址，因此无法说明该网段其余地址的情况。
• unifi-network-cli topology --site default - 将每个已同步的客户端归到它所连接的设备下。列表端点不提供设备间的上行链路信息，因此每台设备都会位于顶层——交换机后面的交换机不会嵌套显示。

更详细的说明请参见 pain-point.md。

常见问题

这能与 ChatGPT 配合使用吗？

当前版本不行。ChatGPT（Plus、Pro、Team、Business、Enterprise 和 Education 计划；Free 计划目前尚未开放 Developer Mode）只能通过 HTTPS 连接远程 MCP 服务，这意味着必须以 HTTP 模式运行 UniFi MCP 服务。在当前版本中，HTTP 模式无需密码，会监听所有网络接口，而且你打开的网页也能访问它。因此，在重新发布连接器之前，请勿运行该模式或将其置于隧道后方；mcp-install.md 中的安全说明解释了原因。在此之前，请使用 Claude Desktop、Claude Code 或 Codex。

这能与 Codex、Cursor、Windsurf、Cline、Copilot 或 Gemini 配合使用吗？

可以——它们都支持 MCP。上方的矩阵中列出了跨工具安装命令，docs/which-agent.md 中则有深入介绍。

我需要懂编程吗？

不需要。推荐的安装方式是向 Claude Code 或 Codex 粘贴一句话——你的 Agent 会读取 SKILL.md 并完成安装。备用方式是使用适用于各操作系统的一行安装命令（bash 或 PowerShell）。这两种方式都不需要编写代码。你只需输入一次 UniFi 凭据。

我的 UniFi 数据安全吗？

你的数据会保留在自己的计算机上。CLI 和 MCP 服务都是本地二进制文件。SQLite 镜像存放在你用户帐户下的目录中。AI Agent 只能看到 CLI 返回的内容——通常是查询结果，而不是原始的批量数据。凭据从你的环境或 Agent 配置中读取；MSP Skills 绝不会将其打包进此仓库或传输到任何地方。

这会使用 UniFi Site Manager 云 API 吗？

不会。此技能会通过你在网关自带 UI 中生成的 API 密钥，调用可自托管的 UniFi OS 网关上的本地 Network 集成 API，访问地址为 https://<gateway>/proxy/network。这是单网关工具：一个 CLI 实例只能查看一个控制器，不提供跨所有部署的多租户视图。UniFi Protect（摄像头）和 UniFi Access（门禁）使用独立的 API，不在支持范围内。

为什么 drift 和 newcomer 首次运行时没有报告任何内容？

它们各自都会维护基线，因为 API 不提供可读取的历史记录。首次对某个站点运行时，会将当前状态记录为基线，并且不报告任何更改——这是预期行为，并非错误。从第二次运行开始，它们会报告自上次运行以来发生的变化。每次检查前运行 unifi-network-cli sync，确保镜像是最新的。

更改防火墙前，我可以信任 rule-predict 吗？

请将其视为本地模拟，而非实时流量跟踪。它会按网关采用的索引升序、首条匹配即生效的顺序遍历上次同步的防火墙策略，并且仅匹配源 IP 和目标 IP——--port 会回显以供参考，但不参与匹配。对于它无法解析的全局区域策略和流量匹配列表引用，它会标记为不确定，而不会默认为匹配。请先同步，并在控制台中确认实际更改。

它会取代 UniFi 控制台吗？

不会，也并非为了取代控制台。控制台仍然是系统的记录来源，也是你进行更改的地方。此工具补充了控制台所不具备的功能：配置偏差检测、首次发现的硬件、端口和 PoE 余量，以及防火墙匹配预测。它们都能通过单条命令返回 Agent 可操作的 JSON。

费用是多少？

免费，采用 Apache-2.0 许可证。你只需为使用的 AI Agent（Claude、ChatGPT、Codex 等）付费，费用由你的 AI 提供商收取，而非我们。

安全模型

层级	示例	推荐的 Agent 策略
读取	drift、newcomer、topology、port-audit，以及不会修改数据的 sites ... 端点，以下会返回机密的命令除外。请注意，drift 和 newcomer 每次运行都会更新各自的本地基线。	允许
凭据（包括返回机密的读取操作）	auth set-token、auth logout，以及所有输出可能包含有效机密的命令——CLI 不会隐藏任何内容：sites wifi get-broadcast-details（该 SSID 的明文密码）、sites hotspot get-voucher / get-vouchers、guest report、search 和 analytics --type hotspot --group-by code（可用的访客代金券码）	仅限人在回路中——切勿纳入“一律允许读取”的策略。还有 3 个写入命令也会返回机密（sites hotspot create-vouchers、sites wifi create-broadcast / update-broadcast）——对其输出也应采用相同的处理方式。
写入（常规）——18 个命令	sites firewall create-policy、sites acl-rules update、sites networks create、sites wifi update-broadcast、sites dns create-policy、sites hotspot create-vouchers	使用 --dry-run 预览，然后在审核后写入
设备 / 端口控制——4 个命令	sites devices adopt、sites devices execute-adopted-action、sites devices execute-port-action、sites clients execute-connected-action	仅限人在回路中——端口操作可能会让 PoE 设备断电重启，并断开插在该端口上的任何设备
破坏性操作——10 个命令	sites devices remove（如果设备在线，会将其恢复出厂设置）、sites firewall delete-zone、sites networks delete、sites acl-rules delete、sites wifi delete-broadcast	仅限人在回路中，并须明确确认

有两点需要提前了解。此 CLI 本身不实施权限隔离，因此你的 API 密钥被允许执行的操作，任何命令都能执行——运行 drift 的凭据也可能运行 sites devices remove，因此必须在 Agent 策略中设置防护机制。此外，“一律允许读取”在此并非安全策略：CLI 不会隐藏响应正文，因此 sites wifi get-broadcast-details 会以明文形式返回某个 SSID 的预共享密钥，而 guest report 和 search 会直接从本地镜像返回有效的访客代金券码。完整详情（包括如何限制权限）请参阅 governance.md。

状态

Beta 版，等待实时验证。命令范围已根据 UniFi Network 集成 API 的公开规范和 CLI 自带的模拟验证套件进行验证（生成运行记录中的 live_api_verification 为未验证）；目前还没有 MSP 在生产网关上运行该工具后提供闭环验证回执。我们在每周的 Build Sessions 中与 MSP 一起验证技能——请在 compoundingteams.com/build-sessions 报名。

---

标准。 符合开放的 Agent Skills 规范（Anthropic，2025 年 12 月；支持 40 多个 Agent）。兼容 MCP——适用于任何支持 MCP 的 Agent，包括 Hermes。已为 OpenClaw 做好准备（frontmatter 已预先配置，等待 OpenClaw 发布）。

归属。 底层 CLI 由 Ricardo Cabral（@phoenix-server）生成并贡献，现依据 Apache-2.0 许可证在此重新分发，并在 cli/NOTICE 中保留原始 NOTICE。

由 Servosity 打包并维护。采用 Apache-2.0 许可证。使用 CLI Printing Press 构建。最后更新：2026-08-14。