金大哥 - opensentry-mcp MCP 详情

article

README

🚀 OpenSentry MCP Server

OpenSentry MCP Server 是 OpenSentry 指挥中心的只读 MCP 服务器。它允许像 OpenCode 和 Claude Code 这样的 AI 助手通过标准化的 MCP 接口查询摄像头状态、带有位置数据的检测警报、录像以及系统健康状况。

✨ 主要特性

| 类别 | 功能 | |------|------| | 摄像头 | 列出所有摄像头，获取状态，访问视频流 URL | | 警报 | 查询带有运动区域/边界框数据的运动/人脸/物体检测警报 | | 分析 | 运动热点热力图、活动时间线、模式检测 | | 录像 | 浏览可用的录像和快照 | | 系统 | 检查系统健康状况，查看设置，访问审计日志 |

运动区域数据

警报包含运动区域坐标，使 AI 无需视觉能力就能了解画面中活动发生的位置：

🚶 [2026-01-22T08:13:09] camera_name: motion (0.0% confidence) at (560, 333) size=29x32

区域：{x, y, width, height} - 检测到的运动的边界框
AI 可以推断："在画面的右上角区域检测到运动"
对模式分析和位置感知查询很有用

🚀 快速开始

git clone https://github.com/SourceBox-LLC/OpenSentry-MCP.git
cd OpenSentry-MCP
./setup.sh
# 按照提示输入你的 OpenSentry URL 和管理员凭据

然后启动服务器：

source .venv/bin/activate
uv run python -m opensentry_mcp

📦 安装指南

手动安装

# 克隆仓库
git clone https://github.com/SourceBox-LLC/OpenSentry-MCP.git
cd OpenSentry-MCP

# 如果你没有安装 uv，安装它
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate  # 在 Windows 上使用 .venv\Scripts\activate
uv sync

配置

创建一个 .env 文件或设置环境变量：

OPENSENTRY_URL=https://localhost:5000
OPENSENTRY_USERNAME=admin
OPENSENTRY_PASSWORD=your_password

从你的指挥中心的 设置 > 用户管理 中获取凭据。

运行

# 使用 stdio 传输运行（默认，适用于 Claude Desktop/OpenCode）
uv run python -m opensentry_mcp

# 使用 HTTP 传输运行
uv run python -m opensentry_mcp --transport http --port 8000

💻 使用示例

可用工具

| 工具 | 描述 | |------|------| | list_cameras() | 列出所有摄像头及其状态 | | get_camera(camera_id) | 获取特定摄像头的详细信息 | | get_camera_feed_url(camera_id) | 获取实时视频流 URL | | get_alerts(detection_type, since_hours) | 获取带有区域数据的检测警报（运动、人脸、物体或全部） | | get_security_summary(since_hours) | 获取整体安全摘要 | | get_motion_hotspots(camera_id, since_hours, grid_size) | 分析运动检测以找到活动热点（热力图） | | get_activity_timeline(camera_id, since_hours, interval_minutes) | 检测活动随时间的时间线 | | get_recordings(camera_id) | 获取可用的录像 | | get_snapshots(camera_id) | 获取可用的快照 | | get_audit_logs(limit) | 获取审计日志（管理员） | | get_settings() | 获取当前配置 | | check_system_health() | 检查系统健康状况 |

警报数据格式

每个警报包含：

{
  "id": 872,
  "camera_id": "driveway",
  "type": "motion",
  "confidence": 0.0,
  "region": {
    "x": 280,
    "y": 279,
    "width": 18,
    "height": 45
  },
  "timestamp": "2026-01-22T08:02:21.152631",
  "processed": false
}

与 AI 助手连接后的查询示例

基础查询

"我有哪些摄像头，哪些是在线的？"
"给我展示过去 24 小时的所有运动警报"
"给我今天的安全摘要"
"我的所有摄像头是否都正常工作？"

活动分析

"我不在的时候发生了什么？"
"给我展示今天早上的所有运动警报"
"哪个摄像头今天检测到的活动最多？"

分析（使用运动节点）

"给我展示运动发生位置的热力图"
"一天中活动最繁忙的时间是什么时候？"
"我的摄像头视野中哪些区域运动最多？"
"给我展示检测的每小时细分情况"

区域感知查询（使用运动节点）

"画面中哪里检测到了运动？"
"摄像头视野的哪些区域活动最多？"
"给我展示画面左侧有运动的警报"

📚 详细文档

资源

| 资源 | 描述 | |------|------| | cameras://all | 所有摄像头信息的结构化数据 | | camera://{id} | 特定摄像头的详细信息 | | alerts://{hours} | 指定时间段内的警报 | | recordings://{id} | 某个摄像头的录像（使用 "all" 表示所有） | | system://status | 整体系统状态 |

预构建提示模板

daily_security_summary - 生成每日安全报告
what_happened_while_i_was_away - 总结不在期间的活动
camera_activity_report - 每个摄像头的活动细分

🔧 技术细节

开发

# 安装开发依赖
uv sync --extra dev

# 热重载运行（需要 mcp[cli]）
mcp dev src/opensentry_mcp/server.py

# 运行测试
uv run pytest

要求

Python 3.10+
uv（包管理器）
可访问运行中的 OpenSentry 指挥中心
指挥中心的管理员凭据

项目结构

opensentry-mcp/
├── setup.sh              # 快速设置脚本
├── pyproject.toml        # 项目配置（uv）
├── README.md             # 本文件
├── .env.example          # 环境模板
├── .venv/                # 虚拟环境
└── src/opensentry_mcp/
    ├── __init__.py       # 包导出
    ├── __main__.py       # 入口点
    ├── client.py         # OpenSentry API 客户端
    └── server.py         # 带有工具的 FastMCP 服务器

更新日志

v0.3.0

新增 get_motion_hotspots() - 运动检测位置的热力图分析
新增 get_activity_timeline() - 随时间的每小时/每日检测模式
基于网格的热点分析将画面划分为可配置的单元格（默认 10x10）
时间线显示按时间间隔的检测频率

v0.2.0

警报中添加运动区域/边界框数据
AI 现在可以了解画面中运动发生的位置
简化警报工具（移除包装函数）
更新显示格式以显示区域坐标

v0.1.0

初始版本
摄像头列表和状态
警报查询（运动、人脸、物体）
录像和快照
系统健康和设置
审计日志

opensentry-mcp