Opensentry MCP

🚀 OpenSentry MCP Server

A read-only MCP server for OpenSentry Command Center. It allows AI assistants such as OpenCode and Claude Code to query camera status, detection alerts with location data, recordings, and system health via a standardized MCP interface.

✨ Features

Motion Region Data

Alerts include motion region coordinates, enabling 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

📦 Installation

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

📚 Documentation

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

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

💻 Usage Examples

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

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

🔧 Technical Details

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