UniFi Protect MCP Server

关键词

UniFi ProtectLLM toolsAI integrationHTTP REST proxylive view

使用说明（Markdown格式）

  • 项目简介

    • 该仓库实现了一个基于 MCP（Model Context Protocol）的服务器端，用于将 UniFi Protect 的 Integration REST API 转换为一组可通过 MCP 客户端（如 Claude Code）调用的“工具”（Tools），同时提供对资源的读取、工具执行、以及提示模板等能力。服务器内置 33 个工具，涵盖系统信息、设备与场景的查询与操作，以及文件上传等功能，并实现了只读模式、安全审查和 dry-run 预览等特性。

  • 主要功能点

    • MCP 服务器核心：实现通过 MCP 服务器注册多种工具、处理 JSON-RPC 风格请求与响应、支持会话管理与能力声明。
    • 资源与数据访问：提供对 UniFi Protect 中 NVR、摄像机、灯、传感器、铃铛、观众、直播视图等资源的读取接口。
    • 工具注册与执行：将 REST API 调用封装为可执行的 Tools，LLM 客户端可按名称调用对应工具。
    • 安全与合规：提供只读模式、明确的注释标签（readOnlyHint、destructiveHint）、以及 confirm/dryRun 机制，防止误操作。
    • 多种传输支持：设计基于 MCP 的通信，理论可扩展到 Stdio、SSE、WebSocket 等传输方式（当前示例使用 Stdio 传输）。
    • 测试和 验证：包含详尽的单元测试，覆盖工具注册、输入模式、dry-run、以及只读/写入权限等场景。

  • 安装步骤

    • 快速开始（npx）
      • 通过 Claude Code 等集成，在工作流中以 npx 调用该 MCP 服务，并通过环境变量提供 UniFi Protect 的地址、API Key 等认证信息。
    • 本地从源码构建
      • git clone https://github.com/owine/unifi-protect-mcp.git
      • cd unifi-protect-mcp
      • 安装依赖：npm install
      • 构建：npm run build
      • 使用示例（需在 MCP 客户端配置中注册服务，具体见下方配置示例）
    • 注意
      • 运行前需要一个 UniFi Protect 系统并开启 Integration API，获取 API key。
      • Node.js 版本建议和仓库需求保持一致。

  • 服务器配置（MCP 客户端使用；客户端配置示例以 JSON 形式表示，非代码块）

    • 服务器名称：unifi-protect
    • 启动命令和参数（示例，实际可根据环境调整）
    • JSON 配置示例（用于 MCP 客户端的启动配置，描述 server name、command、args、env 等信息）:
    • 配置要点说明
      • server name 对应 MCP 服务器的名称，与代码中创建的服务器名称一致
      • command 指定运行 MCP 服务器的命令
      • args 指定启动参数（如暴露的工具集版本、初始化参数等）
      • env 用于注入 UniFi Protect 的主机、API key、以及 SSL 校验等环境变量 下面的 JSON 仅用于示意，具体值请按实际环境填写： { "mcpServers": { "unifi-protect": { "command": "npx", "args": ["-y", "@owine/unifi-protect-mcp@latest"], "env": { "UNIFI_PROTECT_HOST": "192.168.1.1", "UNIFI_PROTECT_API_KEY": "your-api-key", "UNIFI_PROTECT_VERIFY_SSL": "false" } } } }

  • 基本使用方法

    • 通过 MCP 客户端发送 JSON-RPC 请求，指定要执行的工具名（如 protect_list_cameras、protect_get_camera 等）及所需输入参数。
    • 支持只读模式与写入模式，写入工具在执行前会进行确认或 dry-run 预览（如设置 confirm、dryRun 等字段）。
    • 客户端可接收工具执行结果的标准化响应，包含文本化的 JSON 内容或图像等二进制数据的封装。

  • 额外说明

    • 该实现包含 33 个工具（系统、摄像机、设备、现场视图、文件等），并提供 17 个只读工具在只读模式下可用。
    • 安全性设计包括：readOnly 注释、destructive 注释、dryRun 预览，以及对某些操作的 confirm 要求等。

服务器信息

访问项目