CCTV VMS MCP Server for Live and Playback

Overview

This MCP (Model Context Protocol) server provides a bridge between CCTV Video Management Systems (VMS) and clients that consume video via the MCP interface. It exposes MCP-style endpoints to request live streams, request time-based playback on a specific channel, and send playback control commands (play, pause, seek, speed). The server acts as a translator and proxy: it talks to a VMS (RTSP, vendor API, or stream URLs) and exposes simplified, consistent MCP HTTP/JSON endpoints for downstream clients.

This is useful when you need to integrate CCTV streams into analytics pipelines, UI dashboards, or third‑party tools that already speak MCP. Instead of implementing many vendor-specific integrations, clients can call the MCP server to get a live feed or replay recorded footage at a specified wall-clock time and control playback programmatically.

Features

• Proxy live CCTV streams through MCP-compatible endpoints
• Request recorded playback by specifying channel and time range
• Playback control: play, pause, seek, change speed
• Configurable per-channel mappings to VMS streams or API endpoints
• Authentication and TLS support for secure VMS access
• Lightweight deployment: binaries or container image (Docker)
• Simple JSON REST API that fits MCP request/response patterns
• Optional WebSocket or chunked HTTP for streaming data to clients

Installation / Configuration

Below are general installation and configuration examples. Adjust for the language/build system in the repository (build steps are typical but may vary).

Clone and build from source

git clone https://github.com/jyjune/mcp_vms.git
cd mcp_vms

# If the project uses Go (example)
go build -o mcp_vms ./cmd/mcp_vms

# Or use a provided Makefile
make build

Run with a configuration file (YAML)

# config.yml
server:
  listen: "0.0.0.0:8080"
  tls: false

vms:
  # If your VMS has an API, put base URL and credentials
  api_base: "https://vms.example.local/api"
  username: "admin"
  password: "changeme"

channels:
  cam-entrance:
    type: rtsp
    url: "rtsp://vms.example.local/stream/1"
  cam-lobby:
    type: rtsp
    url: "rtsp://vms.example.local/stream/2"

Start the server (binary)

./mcp_vms --config config.yml

Docker (recommended for quick runs)

docker run -p 8080:8080 \
  -v $(pwd)/config.yml:/app/config.yml:ro \
  ghcr.io/your-org/mcp_vms:latest \
  --config /app/config.yml

Configuration options (summary table)

API (Available Resources)

The server exposes a small set of HTTP JSON endpoints that implement MCP-style operations. Example endpoints:

• POST /mcp/v1/stream - request a live stream proxy or URL
• POST /mcp/v1/playback - request playback for a channel at a time range
• POST /mcp/v1/control - control playback (play/pause/seek/speed)
• GET /health - health check

Example: request live stream

curl -X POST "http://localhost:8080/mcp/v1/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "cam-entrance",
    "mode": "live",
    "output": "proxy"  // or "direct" to return native VMS URL
  }'

Response (example)

{
  "status": "ok",
  "stream_url": "http://localhost:8080/streams/abcd1234"
}

Example: request playback by wall-clock time

curl -X POST "http://localhost:8080/mcp/v1/playback" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "cam-lobby",
    "start_time": "2026-04-08T14:30:00Z",
    "end_time": "2026-04-08T14:45:00Z",
    "output": "proxy"
  }'

Playback control (seek / pause / speed)

curl -X POST "http://localhost:8080/mcp/v1/control" \
  -H "Content-Type: application/json" \
  -d '{
    "playback_id": "playback-xyz",
    "command": "seek",
    "timestamp": "2026-04-08T14:35:00Z"
  }'

Notes:

• playback_id is returned when you start a playback session.
• The server may proxy a live chunked stream, return a direct RTSP/HTTP URL, or provide WebSocket streaming depending on configuration and client capability.
• Authentication tokens or Basic Auth may be required if VMS API access needs credentials.

Use Cases

• Live monitoring in unified dashboards: request a consistent stream URL for different vendor VMS systems and render in a web UI without per-vendor logic.
• Post‑incident review: programmatically request playback for the time range surrounding an alarm (e.g., 10 minutes before to 5 minutes after) and archive the proxy stream.
• Analytics pipelines: supply recorded video to an analytics service by requesting playback for a known timestamp window and streaming into a processor.
• Automated evidence export: on event detection, request playback around the event and save the output to object storage for compliance.
• Remote playback control: send play/pause/seek commands from a command center UI to any channel without exposing VMS internals.

Developer Tips

• Map channels centrally: configure channel identifiers that match your UI and map them to VMS stream URLs or API IDs in the config file.
• Use proxy output for consistent authentication