OpenSentry MCP Server

Read-only MCP server for OpenSentry Command Center. Enables AI assistants like OpenCode and Claude Code to query camera status, detection alerts with location data, recordings, and system health through a standardized MCP interface.

Features

| Category | Capabilities | |----------|--------------| | Cameras | List all cameras, get status, access feed URLs | | Alerts | Query motion/face/object detection alerts with motion region/bounding box data | | Analytics | Motion hotspot heatmaps, activity timelines, pattern detection | | Recordings | Browse available recordings and snapshots | | System | Check health, view settings, access audit logs |

Motion Region Data

Alerts include motion region coordinates, allowing AI to understand where in the frame activity occurred without vision capabilities:

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

region: {x, y, width, height} - Bounding box of detected motion
AI can infer: "Motion detected in the top-right area of the frame"
Useful for pattern analysis and location-aware queries

Quick Start

git clone https://github.com/SourceBox-LLC/OpenSentry-MCP.git
cd OpenSentry-MCP
./setup.sh
# Follow the prompts to enter your OpenSentry URL and admin credentials

Then start the server:

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

Manual Installation

# Clone the repository
git clone https://github.com/SourceBox-LLC/OpenSentry-MCP.git
cd OpenSentry-MCP

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv sync

Configuration

Create a .env file or set environment variables:

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

Get credentials from your Command Center at Settings > User Management.

Running

# Run with stdio transport (default, for Claude Desktop/OpenCode)
uv run python -m opensentry_mcp

# Run with HTTP transport
uv run python -m opensentry_mcp --transport http --port 8000

Available Tools

| Tool | Description | |------|-------------| | list_cameras() | List all cameras and their status | | get_camera(camera_id) | Get detailed info for a specific camera | | get_camera_feed_url(camera_id) | Get live video feed URL | | get_alerts(detection_type, since_hours) | Get detection alerts (motion, face, object, or all) with region data | | get_security_summary(since_hours) | Get overall security summary | | get_motion_hotspots(camera_id, since_hours, grid_size) | Analyze motion detection to find activity hotspots (heatmap) | | get_activity_timeline(camera_id, since_hours, interval_minutes) | Timeline of detection activity over time | | get_recordings(camera_id) | Get available recordings | | get_snapshots(camera_id) | Get available snapshots | | get_audit_logs(limit) | Get audit logs (admin) | | get_settings() | Get current configuration | | check_system_health() | Check system health |

Alert Data Format

Each alert includes:

{
  "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
}

OpenCode Configuration

Add to your ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opensentry": {
      "type": "local",
      "command": ["uv", "--directory", "/path/to/OpenSentry-MCP", "run", "python", "-m", "opensentry_mcp"],
      "enabled": true,
      "environment": {
        "OPENSENTRY_URL": "https://localhost:5000",
        "OPENSENTRY_USERNAME": "admin",
        "OPENSENTRY_PASSWORD": "your_password"
      }
    }
  }
}

Claude Code Configuration

Add to your ~/.claude/mcp.json:

{
  "mcpServers": {
    "opensentry": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/OpenSentry-MCP",
        "run",
        "python",
        "-m",
        "opensentry_mcp"
      ],
      "env": {
        "OPENSENTRY_URL": "https://localhost:5000",
        "OPENSENTRY_USERNAME": "admin",
        "OPENSENTRY_PASSWORD": "your_password"
      }
    }
  }
}

Example Usage

Once connected to an AI assistant, you can ask questions like:

Basic Queries

"What cameras do I have and which are online?"
"Show me all motion alerts from the last 24 hours"
"Give me a security summary for today"
"Are all my cameras working properly?"

Activity Analysis

"What happened while I was away?"
"Show me all motion alerts from this morning"
"Which camera detected the most activity today?"

Analytics (with motion node)

"Show me a heatmap of where motion is occurring"
"What are the busiest times of day for activity?"
"Which areas of my camera view have the most motion?"
"Show me an hourly breakdown of detections"

Region-Aware Queries (with motion node)

"Where in the frame was motion detected?"
"What areas of the camera view have the most activity?"
"Show me alerts with motion in the left side of the frame"

Resources

| Resource | Description | |----------|-------------| | cameras://all | All camera information as structured data | | camera://{id} | Specific camera details | | alerts://{hours} | Alerts from specified time period | | recordings://{id} | Recordings for a camera (use "all" for all) | | system://status | Overall system status |

Prompts

Pre-built prompt templates for common queries:

daily_security_summary - Generate a daily security report
what_happened_while_i_was_away - Summarize activity during absence
camera_activity_report - Per-camera activity breakdown

Development

# Install dev dependencies
uv sync --extra dev

# Run with hot reload (requires mcp[cli])
mcp dev src/opensentry_mcp/server.py

# Run tests
uv run pytest

Requirements

Python 3.10+
uv (package manager)
Access to running OpenSentry Command Center
Admin credentials for the Command Center

Project Structure

opensentry-mcp/
├── setup.sh              # Quick setup script
├── pyproject.toml        # Project configuration (uv)
├── README.md             # This file
├── .env.example          # Environment template
├── .venv/                # Virtual environment
└── src/opensentry_mcp/
    ├── __init__.py       # Package export
    ├── __main__.py       # Entry point
    ├── client.py         # OpenSentry API client
    └── server.py         # FastMCP server with tools

Changelog

v0.3.0

Added get_motion_hotspots() - Heatmap analysis of motion detection locations
Added get_activity_timeline() - Hourly/daily detection patterns over time
Grid-based hotspot analysis divides frame into configurable cells (default 10x10)
Timeline shows detection frequency by time interval

v0.2.0

Added motion region/bounding box data to alerts
AI can now understand where in the frame motion occurred
Simplified alert tools (removed wrapper functions)
Updated display format to show region coordinates

v0.1.0

Initial release
Camera listing and status
Alert queries (motion, face, object)
Recordings and snapshots
System health and settings
Audit logs

MCP Servers