UniFi MCP Server

mcp-name: io.github.mikeholownych/unifi-mcp

一个 MCP（Model Context Protocol）服务器，为 Claude 等 AI 助手提供 UniFi Network 和 Protect 基础设施管理与分析能力。

致谢： 本项目最初是 gbassaragh/Unifi-mcp 的一个分支，此后已发展为一个完全独立的项目。感谢 @gbassaragh 提供了出色的起点。

相较于上游的改进

• 修复了本地会话认证路由 — 在 UNIFI_MODE=local 模式下，请求现在会正确使用传统控制器 API（/proxy/network），并采用 cookie + CSRF 会话认证。上游版本无论何种模式都始终通过 Integration API 路由。

• 感知认证模式的 base URL 解析 — api_base_url 现在会遵循所配置的认证模式，而不是无条件返回 Integration API 端点。

• 扩充的测试套件 — 57 个通过的测试，覆盖配置、网络客户端行为、服务器工具注册以及 Protect 集成。

Related MCP server: UniFi MCP Server

功能特性

UniFi Network

• 设备管理：列出、重启、定位和升级 UniFi 设备（AP、交换机、路由器）

• 客户端管理：监控已连接的客户端、阻止/取消阻止、查看流量统计

• 站点管理：查看站点健康状态、网络配置、VLAN 和无线设置

• 统计与监控：事件、警报、速度测试和 DPI 统计

• AI 驱动洞察：网络分析、优化建议和故障排查

UniFi Protect

• 摄像头管理：列出摄像头、查看状态、获取实时快照

• 系统监控：NVR 状态、摄像头健康摘要

• 配件：管理灯光、传感器、门铃和查看器

• Liveviews：访问已配置的摄像头视图布局

多设备支持

• 配置多个 UniFi 设备（网关、NVR 等）

• 按名称定向特定设备 — 所有网络和 Protect 工具都接受可选的 device 参数

• 每设备 API 密钥：每个已配置的设备使用各自的密钥进行认证

• 跨设备混合使用 Network 和 Protect 服务

认证模式

当使用 API 密钥（Integration API）时，部分控制器功能只能通过旧版会话认证（UNIFI_MODE=local）使用：网络事件、警报、DPI 统计、速度测试、WLAN 配置、防火墙规则、端口配置文件和路由表。这些功能的工具会返回清晰的错误并说明如何启用它们，而不是静默失败。洞察工具会优雅降级并报告数据限制。

关于本地账户的说明： 受 MFA 保护的 SSO/Ubiquiti 账户管理员无法完成会话登录。请在您的控制器上创建一个本地管理员（仅限本地访问），用于 UNIFI_MODE=local。

智能体技能

内置技能（位于 skills/）为智能体传授针对此服务器的成熟工作流 — 包括特定控制器的注意事项（Network 10 已移除的端点、zone-pair 规则、WPA3 过渡）。

完整文档：请参阅 SKILLS.md 了解使用指南、预期结果、故障排查以及如何请求新功能。

快速参考

技能如何工作

只需自然地描述您的问题 — 智能体会将您的请求匹配到合适的技能并遵循其工作流：

• “我的网络断了” → unifi-internet-down 诊断 WAN、调制解调器、网关

• “谁在用我的 WiFi？” → unifi-whos-home 列出设备并标记未知设备

• “审计我的网络” → unifi-network-audit 生成完整的健康报告

• “设置我的新电视” → unifi-setup-new-device 指导 WiFi 配对

写入门控技能（上面已标记）会修改您的网络 — 它们总是在应用更改前征求批准。

面向非技术用户的技能会避免行话、解释每个技术术语，并在执行破坏性操作前要求确认。

安装（按项目）：复制到 .claude/skills/：

git clone https://github.com/mikeholownych/unifi-mcp.git
mkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/

有关完整的使用指南、预期结果、故障排查以及如何请求新功能，请参阅 SKILLS.md。

技能通过其普通名称（get_firewall_policies、…）引用 MCP 工具；您的 MCP 客户端会自动为它们添加前缀。

支持的硬件

• UniFi Dream Machine (UDM, UDM-Pro, UDM-SE)

• UniFi Cloud Gateway (UCG-Ultra, UCG-Fiber)

• UniFi Network Video Recorder (UNVR, UNVR-Pro)

• UniFi Network Application (自托管)

• 传统 Cloud Key (Gen1, Gen2, Gen2+)

安装

使用 uv（推荐）

# Clone the repository
git clone https://github.com/mikeholownych/unifi-mcp.git
cd unifi-mcp

# Install dependencies
uv sync

使用 pip

pip install -e .

配置

在项目根目录创建一个 .env 文件（或设置环境变量）。有关所有选项，请参阅 .env.example。

多设备配置（推荐）

配置多个具有不同服务的 UniFi 设备：

UNIFI_DEVICES='[
  {
    "name": "main-gateway",
    "url": "https://192.168.1.1",
    "api_key": "your-gateway-api-key",
    "services": ["network"],
    "site": "default"
  },
  {
    "name": "nvr",
    "url": "https://192.168.1.2",
    "api_key": "your-nvr-api-key",
    "services": ["network", "protect"],
    "site": "default"
  }
]'
UNIFI_VERIFY_SSL=false

设备配置字段：

注意： username 和 password 字段仅对 Protect 事件工具（运动事件、智能检测）为必填。基本的摄像头操作仅凭 API 密钥即可完成。

要创建 API 密钥：

1. 登录您的 UniFi 控制器

2. 转到设置 → 控制平面 → API

3. 使用适当的权限创建新的 API 密钥

旧版单设备配置

为向后兼容，仍支持单设备配置：

UNIFI_MODE=local_api_key
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_CLOUD_API_KEY=your-api-key
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

本地会话认证（传统）

通过用户名/密码认证获得完整功能访问：

UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=local-admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=false

Cloud API (api.ui.com)

用于 Ubiquiti Cloud API 访问：

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

从 unifi.ui.com → API 部分获取您的 API 密钥。

与 Claude Desktop 配合使用

在您的 Claude Desktop 配置中添加以下内容（Linux 上为 ~/.config/claude/claude_desktop_config.json，macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unifi-mcp", "python", "-m", "unifi_mcp.server"],
      "env": {
        "UNIFI_DEVICES": "[{\"name\":\"gateway\",\"url\":\"https://192.168.1.1\",\"api_key\":\"your-key\",\"services\":[\"network\"]},{\"name\":\"nvr\",\"url\":\"https://192.168.1.2\",\"api_key\":\"your-key\",\"services\":[\"network\",\"protect\"]}]",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

与 Claude Code / opencode 配合使用

# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.server

或者在 opencode.json 中：

{
  "mcp": {
    "unifi": {
      "type": "local",
      "command": ["/path/to/unifi-mcp/.venv/bin/python", "-m", "unifi_mcp.server"],
      "enabled": true
    }
  }
}

可用工具

多设备管理

• list_unifi_devices - 列出所有已配置的 UniFi 设备及其服务

设备管理

• list_devices - 列出所有 UniFi 网络设备

• get_device_details - 获取详细的设备信息

• restart_device - 重启设备

• locate_device - 闪烁 LED 以定位设备

• get_device_stats - 获取性能统计

• upgrade_device - 升级固件

• provision_device - 强制重新配置

客户端管理

• list_clients - 列出已连接的客户端

• list_all_clients - 列出所有已知客户端（包括离线）

• get_client_details - 获取客户端详情

• block_client / unblock_client - 阻止/取消阻止客户端

• kick_client - 断开客户端

• forget_client - 从已知客户端中移除

• get_client_traffic - 获取流量统计

• reserve_client_ip - 通过 DHCP 保留机制保留 IP

站点管理

• list_sites - 列出所有站点

• get_site_health - 获取站点健康状态

• get_site_settings - 获取站点设置

• get_sysinfo - 获取系统信息

• get_networks - 获取网络/VLAN 配置

• get_wlans - 获取无线网络配置

• get_port_profiles - 获取交换机端口配置文件

• get_firewall_rules - 获取旧版防火墙规则

• get_firewall_policies - 获取基于区域的防火墙策略（UniFi Network 9+）

• get_routing_table - 获取路由表

• get_port_forwards - 获取端口转发规则

• create_port_forward / delete_port_forward - 管理端口转发

配置管理（写入）

• create_wlan / update_wlan / delete_wlan - 管理无线网络

• create_firewall_policy / set_firewall_policy_enabled / delete_firewall_policy - 管理基于区域的防火墙策略

• export_camera_clip - 将摄像机录像片段导出为 MP4（Protect）

• get_all_sites_health - 所有站点的健康状态概览

会删除数据或造成中断的工具均通过 MCP 注释进行确认门控或被标记为破坏性。

统计与监控

• get_network_health - 网络整体健康状态

• get_recent_events - 最近事件

• get_alarms - 活动警报

• archive_all_alarms - 归档所有警报

• run_speed_test - 开始测速

• get_speed_test_status - 获取测速结果

• get_dpi_stats - DPI 统计信息

• get_traffic_summary - 流量摘要

AI 洞察工具

• analyze_network_issues - 全面问题分析

• get_optimization_recommendations - 配置建议

• get_client_experience_report - 客户端质量指标

• get_device_health_summary - 设备健康状态概览

• get_traffic_analysis - 流量模式分析

• get_all_sites_health - 所有站点的健康状态概览

多站点编排

• get_global_inventory - 所有控制器的统一设备清单

• get_global_health - 所有控制器的汇总健康报告

• get_global_client_summary - 所有控制器的客户端数量、流量最高者、被阻止客户端

• troubleshoot_client - 深度客户端故障排查

UniFi Protect

• list_cameras - 列出所有摄像机及其连接状态

• get_camera_details - 获取详细摄像机信息

• get_camera_snapshot - 获取实时快照（base64 JPEG）

• get_protect_system_info - 获取 NVR 系统信息

• get_camera_health_summary - 摄像机健康状态概览及问题

• get_liveviews - 获取已配置的实时视图布局

• get_protect_accessories - 列出灯具、传感器、门铃、显示器

UniFi Protect 事件（需要用户名/密码）

• get_motion_events - 获取最近运动事件

• get_smart_detections - 获取智能检测事件（人、车辆、动物、包裹）

• get_protect_event_summary - 按类型汇总所有事件

• get_recent_protect_activity - 最近活动的快速概览

示例对话

连接 MCP 服务器后，您可以询问 Claude：

网络管理

• "列出我所有的 UniFi 设备"

• "当前网络健康状态如何？"

• "分析我的网络是否存在任何问题"

• "您有哪些优化建议？"

• "显示客户端体验指标"

• "排查 MAC 地址为 aa:bb:cc:dd:ee:ff 的客户端"

• "哪些客户端占用带宽最多？"

• "是否有设备需要固件更新？"

• "显示最近的网络事件"

• "运行测速"

UniFi Protect

• "列出我所有的摄像机"

• "显示摄像机健康状态摘要"

• "从 Front Door 摄像机获取快照"

• "我的 NVR 状态如何？"

• "是否有摄像机断开连接？"

• "显示 Protect 配件"

Protect 事件（需要凭据）

• "显示最近的运动事件"

• "过去 24 小时内发生了什么智能检测？"

• "今天是否有人体检测？"

• "给我过去一周的事件摘要"

• "显示 Front Door 摄像机的最近活动"

多设备

• "列出我配置的 UniFi 设备"

• "显示我 NVR 上的摄像机"

• "从主网关获取网络健康状态"

开发

运行测试

uv run pytest

代码格式化

uv run ruff check .
uv run ruff format .

Docker

docker build -t unifi-mcp .
docker run -i --rm --env-file .env unifi-mcp

请求新功能

• 新技能：使用 [Skill] 前缀打开一个问题 — 描述问题、工作流程和预期输出

• 修改技能：使用 [Skill: skill-name] 前缀打开一个问题 — 缺少了什么或哪里出了问题

• 新工具：使用 [Tool] 前缀打开一个问题 — 包括 UniFi API 端点和预期格式

有关详细的贡献指南，请参阅 SKILLS.md。

有关发布历史，请参阅 CHANGELOG.md；如需贡献，请参阅 CONTRIBUTING.md。

安全说明

• 凭据通过环境变量传递 — 切勿提交 .env

• 默认情况下，为自签名证书禁用 SSL 验证

• 服务器仅暴露读取操作和安全的管理命令

• 不暴露破坏性操作（删除站点、恢复出厂设置）

• API 密钥应妥善保管并定期轮换

许可证

MIT License

贡献

欢迎贡献！请打开一个问题或提交拉取请求。