使用 LLM 代理管理 UniFi 网络和摄像头
如果你曾在 UniFi Controller 中配置过防火墙，或在 UniFi Protect 中搜索过某个摄像头的特定片段，你就会明白这个过程有多繁琐。你需要打开网页界面，在菜单中层层点击，寻找正确的 VLAN 或客户端 MAC 地址。虽然可以通过脚本实现自动化，但 Ubiquiti 的 API 在某些地方设计得很独特，而且不同版本之间还存在差异。
unifi-mcp 项目采用了不同的方式。它是一组使用 Model Context Protocol (MCP) 的服务器，将 Claude Code、Codex 或 OpenClaw 等 AI 助手与 UniFi 控制器连接起来。
项目内部结构
该仓库采用 Python 和 TypeScript 单体仓库结构，分为三个主要模块，覆盖 Ubiquiti 产品领域：
- Network — 用于管理网络设备的模块。包含 186 个工具，用于操作 VLAN、防火墙、客户端、Wi-Fi 网络和设备。
- Protect — 视频监控工具。包括 61 个函数，用于搜索事件、分析移动检测和操作摄像头。
- Access — 门禁控制管理。包含 36 个函数，用于操作门禁、凭证和访问日志。
此外，该项目还包含一个独立的 REST/GraphQL 服务器，用于尚未支持 MCP 协议的客户端，以及一个 Cloud Relay 系统，用于通过 Cloudflare Workers 将本地网络与远程代理连接起来。
安全性和致命错误防护
让语言模型直接访问你的家庭或办公室网络防火墙是一个大胆的举措。unifi-mcp 开发人员内置了两种安全机制来降低破坏风险。
第一种机制是预览后确认的概念。任何配置更改首先返回预览：AI 代理向你展示它计划发送给控制器的确切 JSON 或规则列表，然后等待你的明确确认。
第二个要素是敏感数据的自动脱敏。默认情况下，所有 Wi-Fi 密码、VPN 密钥、SNMP 团体名和令牌都会从工具响应中剥离，并替换为 ***REDACTED***。模型不会在上下文中看到敏感信息，也不会在日志中意外"泄露"它们。但是，如果你运行的是可信的本地管理脚本，可以通过环境变量禁用脱敏。
实际应用场景
你可以用自然语言向代理编写查询，而不是手动在界面中搜索。
对于网络模块：
- "显示来宾 VLAN 中的所有客户端、信号强度和流量"
- "审计防火墙规则，找出重复和冲突的策略"
- "创建一条规则，从午夜到早上 6 点阻止物联网设备的互联网访问"
对于安全系统：
- "查找本周入口处的所有车辆识别事件"
- "交叉比对时间戳：凌晨 2 点谁在前门刷了门禁卡，以及附近哪个摄像头在同一时刻记录了移动画面"
顺便说一下，对于频繁执行的任务，仓库已经为代理内置了技能。例如，防火墙审计器运行 16 项网络安全检查，输出 100 分制的评分并附带修复建议。
技术实现原理
该项目积极利用最新 MCP 协议版本的功能。由于包含 186 个函数的工具可能会在对话开始前就填满 LLM 的上下文窗口，因此这里实现了延迟发现机制。最初，服务器只向助手传递搜索元工具，具体端点按需加载。
在本地环境中启动服务器通过 uvx 一条命令即可完成：
uvx unifi-network-mcp@latest
uvx unifi-protect-mcp@latest
uvx unifi-access-mcp@latest
配置通过环境变量传递。你需要一个 UniFi 控制器上的本地管理员账户才能连接。注意：启用双因素身份验证或使用 Ubiquiti SSO 的账户无法使用——你需要为 MCP 创建一个单独的本地服务用户。
Claude Desktop 配置示例：
{
"mcpServers": {
"unifi-network": {
"command": "uvx",
"args": ["unifi-network-mcp@latest"],
"env": {
"UNIFI_HOST": "192.168.1.1",
"UNIFI_USERNAME": "mcp-service-account",
"UNIFI_PASSWORD": "your-safe-password"
}
}
}
}
是否值得一试
该项目在其类别中看起来已经相当成熟：GitHub 上 588 颗星、活跃的提交记录以及对 Python 3.13+ 的支持。它对系统管理员、Home Assistant 爱好者和在 Ubiquiti 之上构建自动化的人都有帮助。
如果你家里只有一个接入点，设置 MCP 服务器意义不大。但对于包含防火墙、摄像头和门禁控制的复杂基础设施，能够向代理提问而不是手动在仪表板中搜索，可以节省大量时间。
相关项目