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