UniFi Protect MCP

UniFi Protect MCP 服务器

为 AI 助手及其他支持 MCP 的客户端提供 UniFi Protect 工具的 MCP 服务。可查询摄像头、事件、智能检测、「查找所有内容」检测搜索、录像、灯光、传感器、蜂鸣器、已知人脸、车牌和 Alarm Manager，并采用默认安全的权限设置，所有变更操作都须先预览再确认。

通过 HTTP 集成的软件，包括自动化服务和 MCP 适配器，应使用 unifi-api-server 执行 REST 和 GraphQL 查询、操作及 SSE 事件。

安装

Claude Code（推荐）

此插件会安装 MCP 服务、用于发现工具的 Agent 技能，以及引导式设置命令：

/plugin marketplace add sirkirby/unifi-mcp
/plugin install unifi-protect@unifi-plugins

然后运行交互式设置，配置控制器连接：

/unifi-protect:unifi-protect-setup

此流程会引导你输入控制器主机、凭据和权限偏好。凭据通过文件或命令提供，不会在聊天中输入。设置结果会保存为插件的 Claude Code 选项，并应用于每个项目；作为选项输入的密码或 API 密钥会存储在系统钥匙串中。完成设置后，启动新的 Claude Code 会话以连接。

从 1.0.0 之前的插件版本升级，该版本将设置保存在项目的 .claude/settings.local.json 中？请参阅插件升级指南。

Codex

注册市场，然后在 Codex 的 /plugins 界面中安装 unifi-protect：

codex plugin marketplace add sirkirby/unifi-mcp

安装后，让 Codex 使用 UniFi Protect 设置技能。设置会将版本固定的 MCP 服务条目及控制器设置保存到 Codex 的 config.toml 中，并提示你重启 Codex。每次升级插件后，都使用 --refresh 重新运行设置。

PyPI / Docker

# PyPI
uvx unifi-protect-mcp@latest
# or: pip install unifi-protect-mcp

# Docker
docker pull ghcr.io/sirkirby/unifi-protect-mcp:latest

# From source
git clone https://github.com/sirkirby/unifi-mcp.git
cd unifi-mcp && uv sync

使用示例

连接后，只需用自然语言向 AI Agent 提问：

“列出过去一小时检测到运动的所有摄像头”

“显示今天前门摄像头的智能检测事件——仅限人员和车辆”

“查找本周车道中的白色厢式货车检测记录”

“本周哪些摄像头的运动事件最多？有没有异常模式？”

“有没有摄像头离线或连接质量下降？”

“显示昨晚凌晨 2 点到 5 点之间车道摄像头的所有录像事件”

“今天哪些传感器触发了警报？读数是多少？”

所有摄像头和事件查询默认均为只读。变更操作（摄像头设置、灯光控制）须遵循先预览再确认流程。

配置

在服务器的进程环境中设置这些变量。插件设置技能已为 Codex 和 OpenClaw 完成此操作；在 Claude Code 中，插件会将其选项映射到这些变量。服务器不会自动加载 .env 或工作目录中的 YAML 文件；请在启动器中显式加载可信的环境文件（支持 Docker env_file:），或使用绝对路径 CONFIG_PATH 选择自定义 YAML。迁移示例请参阅配置。

如果未配置控制器主机，服务器仍会以设置模式启动：告知客户端如何进行配置，仅提供只读的 protect_setup_status 工具，并且不会连接任何控制器。

# Server-specific variables (recommended)
UNIFI_PROTECT_HOST=192.168.1.1      # Controller IP or hostname
UNIFI_PROTECT_USERNAME=admin         # Local admin username
UNIFI_PROTECT_PASSWORD=your-password # Admin password
# Optional:
# UNIFI_PROTECT_API_KEY=             # Required for camera HDR/mic volume and light power/brightness/PIR settings
# UNIFI_PROTECT_PORT=443             # Controller HTTPS port
# UNIFI_PROTECT_VERIFY_SSL=false     # SSL certificate verification

摄像头 HDR 和麦克风音量，以及泛光灯功率、亮度、PIR 灵敏度和持续时间，现在使用 uiprotect 16.x 提供的 Protect 公共 Integration API。 使用这些设置前，请设置 UNIFI_PROTECT_API_KEY（或共享备用变量 UNIFI_API_KEY），然后重启服务器。其他 Protect 操作仍需会话凭据。缺少密钥或设备 ID 与公共 API 不兼容时，会在写入请求中的任何设置之前失败。

麦克风音量更新接受 1–100；公共 API 不接受 0。保留现有 HDR 别名：true/on/normal 表示 auto，false 表示 off，而 always/superHdr 表示公共 HDR 的 on。灯光亮度仍为 1–6，灵敏度为 0–100，持续时间为 15–900 秒。light_on 和 is_light_on 是等效输入，用于控制强制照明；关闭强制照明不会停用运动触发照明。

设置更新仍受预览/确认和策略门控约束。写入前会验证请求；控制器故障仍可能导致部分更新。更新失败时会返回错误及已应用的设置，调用方可先检查当前状态，再重试。

备用方案： 共享的 UNIFI_* 变量（例如 UNIFI_HOST）也可使用。服务器会优先检查 UNIFI_PROTECT_*，若未设置服务器专用变量，则回退到 UNIFI_*。对于单控制器配置，只需使用共享变量。

MCP 响应大小

对于已提供结构化输出的工具结果，默认响应模式为 adaptive。它根据 MCP 初始化期间公布的规范日期格式 protocolVersion 对每个请求进行分类，而不依据客户端的产品名称或应用版本。对于公布 MCP 2025-06-18 或更高版本的请求，响应会在 content 中提供简洁内容，并在 structuredContent 中完整提供一次结果；对于公布更早版本（如 2024-11-05 或 2025-03-26）的请求，或版本元数据缺失或格式错误的请求，则会在 content 中保留完整的兼容性 JSON。将 UNIFI_PROTECT_MCP_CONTENT_MODE 设为 compat，可强制使用重复的兼容格式；设为 compact，可在协商请求之外强制使用简洁文本加完整结构化输出。此服务专用变量优先于 UNIFI_MCP_CONTENT_MODE；对于任何只从 content 获取完整结果的客户端，无论其公布的版本如何，都应使用 compat。

惰性加载元工具（*_tool_index、*_execute、*_batch、*_batch_status 和仅用于惰性加载的 *_load_tools）仍然仅提供 content；它们不属于上述 2025-06-18 之前的协议类别。对于结构化的内部结果，*_execute 和 *_batch_status 会在 content 中提供一个规范化的 JSON 载荷，而不是嵌套的传输对；仅提供 content 的执行结果保持不变。响应模式不会将这些元工具转换为使用 structuredContent。

启用 Network 并同时启用 Protect 时，其最大来源响应会分别受到限制：unifi_get_dashboard 默认使用 summary=true，而 unifi_list_rogue_aps 默认返回最多包含 100 条记录的摘要页面；summary=false 会恢复完整的所选数据。

AI 驱动的警报需要 SuperAdmin。 警报规则工具（protect_alarm_list_rules / protect_alarm_get_rule / protect_alarm_create_rule / protect_alarm_update_rule / protect_alarm_delete_rule）会在账号为 SuperAdmin 时透明地使用现代 UniFi-OS Alarm Manager，否则回退到经典自动化视图。现代路径会显示和管理 AI 驱动的警报（例如 AI Natural Language）；旧版路径无法查看这些规则，且响应会包含一条标准 MCP _meta 提示，说明视图受限。要查看或管理 AI 警报，请在运行 Protect 的控制台上为账号授予 SuperAdmin 权限。影响范围：在独立的 UNVR 上，权限仅限于 Protect；在组合式 UDM 控制台上，SuperAdmin 还会授予 Network/UniFi-OS 控制权限。

敏感响应字段

Protect 工具在向 MCP 客户端返回数据前，默认会对包含机密信息的流字段进行脱敏。这包括来自 protect_get_camera_streams 的 RTSP/RTSPS 流别名和 URL。当可信的本地管理进程需要原始流值时，可将 UNIFI_PROTECT_REDACT_SENSITIVE_FIELDS=false 或全局 UNIFI_REDACT_SENSITIVE_FIELDS=false 策略标志设为禁用脱敏。

运行

# stdio transport (default -- for Claude Desktop, LM Studio, etc.)
unifi-protect-mcp

# Docker
docker run -i --rm \
  -e UNIFI_PROTECT_HOST=192.168.1.1 \
  -e UNIFI_PROTECT_USERNAME=admin \
  -e UNIFI_PROTECT_PASSWORD=secret \
  ghcr.io/sirkirby/unifi-protect-mcp:latest

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "unifi-protect": {
      "command": "uvx",
      "args": ["unifi-protect-mcp"],
      "env": {
        "UNIFI_PROTECT_HOST": "192.168.1.1",
        "UNIFI_PROTECT_USERNAME": "admin",
        "UNIFI_PROTECT_PASSWORD": "your-password"
      }
    }
  }
}

功能

• 摄像头 -- 列出、检查、拍摄快照、查看 RTSP 流、PTZ 控制、设置、录制开关、重启
• 事件 -- 查询历史事件、智能检测（人员/车辆/动物/包裹）、查找任何内容的检测搜索、缩略图
• 实时流 -- WebSocket 事件缓冲区，支持 MCP 资源订阅和轮询
• 录制 -- 状态、可用性、支持延时摄影的片段导出
• 已知人脸 -- 列出、重命名、合并和移除人脸识别组
• 设备 -- 灯具（亮度、PIR 灵敏度）、传感器（温度、湿度、运动）、门铃（音量、触发）
• 实时视图 -- 列出和检查多摄像头布局
• 系统 -- NVR 信息、健康指标、固件状态、已连接的查看者

Agent 技能

Protect 插件附带一项可与 MCP 工具配合使用的 Agent 技能：

安全摘要

跨产品事件情报，可汇总所有已连接的 UniFi 系统并生成简明的安全摘要。

• 来源： Protect 摄像头事件、Access 门禁事件、Network 防火墙活动
• 严重程度分类： 根据时段背景（工作时间、非工作时间或深夜）和事件类型（人员检测、车辆、门禁访问、防火墙拦截等）对事件进行分类
• 跨产品关联： 五条内置关联规则可发现跨产品的模式：
  • 门口摄像头检测到移动，但没有对应的刷卡记录
  • 短时间内多次门禁访问失败
  • 人员检测与同一时段的防火墙拦截同时发生
  • 非工作时间的摄像头活动没有对应的 Access 事件
  • 周界反复检测到车辆
• 活动计数： 汇总所有来源的总数，便于快速了解概况

安装插件后，通过技能命令调用：

/unifi-protect:security-digest

事件改进

事件响应中的 camera_name

现在，所有与事件相关的工具都会在每个事件对象中同时返回 camera_name 和 camera_id。摄像头名称从启动时缓存的引导数据中解析，无需额外的 API 调用。

受影响的工具：protect_list_events、protect_list_smart_detections、protect_recent_events

之前：

{ "camera_id": "abc123", "type": "motion", ... }

之后：

{ "camera_id": "abc123", "camera_name": "Front Door", "type": "motion", ... }

这样就无需再单独调用 protect_list_cameras 来将 ID 映射为名称。

紧凑模式

protect_list_events 和 protect_list_smart_detections 接受 compact=true 参数，可从响应中移除低信号字段：thumbnail_id、category、sub_category 和 is_favorite。这样生成的响应体积约可缩小 40%。

# Standard call
protect_list_events(limit=50)

# Compact — recommended for digests, summaries, and context-constrained workflows
protect_list_events(limit=50, compact=True)

在生成摘要或将事件传入对 token 预算敏感的下游提示词时，建议默认使用紧凑模式。

文档

• 配置 -- 完整的环境变量参考、YAML 配置、Protect 专属选项
• 权限 -- 权限系统、类别默认值、如何启用变更操作
• 工具目录 -- 按类别整理的全部 63 个工具
• 事件流 -- 实时事件架构、MCP 资源、轮询
• 故障排除和支持包 -- 经审核的支持证据、连接问题、SSL、缺失的工具

开发

cd apps/protect
make test         # Run tests
make lint         # Lint
make format       # Format
make manifest     # Regenerate tools_manifest.json
make pre-commit   # All of the above

完整的 Monorepo 工作流请参阅根目录中的 CONTRIBUTING.md。

许可证

MIT