DVR-FFmpeg-MCP-Server

BigDon86/DVR-FFmpeg-MCP-Server

3.1

If you are the rightful owner of DVR-FFmpeg-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for natural language video clip extraction from DVR files using FFmpeg.

Tools
6
Resources
0
Prompts
0

DVR FFmpeg MCP Server

A Model Context Protocol (MCP) server for natural language video clip extraction from DVR files using FFmpeg.

Features

  • Natural Language Time Parsing: Extract clips using intuitive time expressions like "5:30", "5 minutes from start", or "17:27:46"
  • DVR File Discovery: Automatically find and parse DVR files with camera names and timestamps
  • Video Metadata: Get detailed information about video files using ffprobe
  • Video Stitching: Concatenate multiple video clips into a single file
  • Side-by-Side Video Combination: Combine multiple camera feeds into synchronized split-screen layouts
  • Cross-Platform: Works on Windows and Linux systems

Requirements

  • Python 3.7+
  • FFmpeg and ffprobe installed and available in PATH
  • DVR files in the expected naming format: {Camera}-{StartTime}-{EndTime}.mp4

Installation

  1. Ensure FFmpeg is installed:

    # Windows (using chocolatey)
choco install ffmpeg

# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install ffmpeg

# macOS (using homebrew)
brew install ffmpeg

  2. Clone or download this repository

  3. The server is ready to use - no additional dependencies required beyond Python standard library

DVR File Format

The server expects DVR files to follow this naming convention:

{Camera}-{StartTime}-{EndTime}.mp4

Example: FrontDrive-20250905172746904-20250905182746904.mp4

Where:

  • FrontDrive is the camera name
  • 20250905172746904 is the start timestamp (YYYYMMDDHHMMSSMMM format)
  • 20250905182746904 is the end timestamp (YYYYMMDDHHMMSSMMM format)

Usage

Running the Server

python DVR-FFmpeg-MCP-Server/src/dvr_ffmpeg_mcp_server.py

Available Tools

1. find_dvr_files

Search for DVR files by various criteria:

{
  "camera_name": "FrontDrive",
  "start_date": "2025-09-05",
  "end_date": "2025-09-06"
}
2. extract_clip

Extract video clips with natural language time specifications:

{
  "video_path": "D:/DVRStorage/DVR/1/FrontDrive-20250905172746904-20250905182746904.mp4",
  "start_time": "5:30",
  "duration": "2 minutes"
}

Supported time formats:

  • "5:30" - 5 minutes 30 seconds from start
  • "17:27:46" - Absolute time (if matches DVR timestamp)
  • "5 minutes from start" - 300 seconds offset
  • "120" - 120 seconds (plain numbers)
3. get_video_info

Get detailed video metadata:

{
  "video_path": "path/to/video.mp4"
}
4. stitch_videos

Concatenate multiple video files into a single continuous video:

Parameters:

  • input_files (required): List of video file paths to concatenate
  • output_path (required): Output file path for the stitched video
  • method (optional): Concatenation method - "concat" (faster, same format) or "filter" (different formats). Default: "concat"

Methods:

  • "concat": Uses FFmpeg's concat demuxer - faster for files with identical format/codec
  • "filter": Uses FFmpeg's filter_complex - handles different formats/resolutions

Example:

{
  "input_files": [
    "D:/DVRStorage/Clips/1/videoclip-20250907134400000-20250907134430000.mp4",
    "D:/DVRStorage/Clips/1/videoclip-20250907134430000-20250907134500000.mp4",
    "D:/DVRStorage/Clips/1/videoclip-20250907134500000-20250907134530000.mp4"
  ],
  "output_path": "D:/DVRStorage/MultiClips/continuous-90-second-sequence.mp4",
  "method": "concat"
}

Use Cases:

  • Sequential Timeline Creation: Combine multiple time-based clips into one continuous video
  • Gap-Free Playback: Stitch adjacent time periods without interruption
  • Long Duration Assembly: Create extended clips from multiple shorter segments
  • Multi-Camera Sequential: Combine clips from the same camera across different time periods
5. combine_videos_side_by_side

Combine multiple video files into synchronized split-screen layouts:

{
  "input_files": ["feed1_clip.mp4", "feed2_clip.mp4"],
  "output_path": "combined_split_screen.mp4",
  "layout": "horizontal",
  "output_resolution": "2560x720",
  "audio_source": "first"
}

Layout Options:

  • "horizontal" - Side-by-side layout (default)
  • "vertical" - Top and bottom layout
  • "grid" - 2x2 grid layout (for 3-4 videos)

Audio Source Options:

  • "first" - Use audio from first video (default)
  • "mix" - Mix audio from all videos
  • "0", "1", etc. - Use audio from specific video by index

Key Features:

  • Automatic video scaling to match layout requirements
  • Support for 2-4 input videos
  • Handles video-only files (no audio streams)
  • Auto-calculates output resolution if not specified
6. list_cameras

Discover available cameras and their file statistics:

{
  "root_paths": ["D:/DVRStorage/DVR/1", "D:/DVRStorage/DVR/2"]
}

Configuration

Default DVR Paths

The server searches these paths by default:

  • D:/DVRStorage/DVR/1
  • D:/DVRStorage/DVR/2

You can override these by providing root_paths parameter to relevant tools.

Natural Language Time Parsing

The server supports various natural language time expressions:

ExpressionMeaning
"5:30"5 minutes 30 seconds from video start
"17:27:46"Absolute time (17:27:46) if within DVR timeframe
"5 minutes from start"300 seconds from video start
"30 seconds"30 seconds duration
"120"120 seconds (plain number)

Example Workflows

Basic Clip Extraction

  1. Find DVR files for a specific camera:

    {
  "tool": "find_dvr_files",
  "arguments": {
    "camera_name": "FrontDrive",
    "start_date": "2025-09-05"
  }
}

  2. Extract a clip from a specific time:

    {
  "tool": "extract_clip",
  "arguments": {
    "video_path": "D:/DVRStorage/DVR/1/FrontDrive-20250905172746904-20250905182746904.mp4",
    "start_time": "2:30",
    "duration": "1 minute"
  }
}

  3. Get video information:

    {
  "tool": "get_video_info",
  "arguments": {
    "video_path": "FrontDrive_clip_150s_60s.mp4"
  }
}

Creating Synchronized Side-by-Side Videos

Step 1: Find DVR files covering the desired time period

{
  "tool": "find_dvr_files",
  "arguments": {
    "start_date": "2025-09-07",
    "end_date": "2025-09-07"
  }
}

Step 2: Extract synchronized clips from multiple cameras

For perfect synchronization, calculate the exact time offset for each camera:

  • Current time: 2:34 PM
  • Desired time: 50 minutes ago = 1:44 PM (13:44:00)
  • FrontDrive file starts at 13:27:46, so offset = 13:44:00 - 13:27:46 = 974 seconds
  • BackDrive file starts at 13:28:17, so offset = 13:44:00 - 13:28:17 = 943 seconds
{
  "tool": "extract_clip",
  "arguments": {
    "video_path": "D:/DVRStorage/DVR/1/FrontDrive-20250907172746904-20250907182746904.mp4",
    "start_time": "974",
    "duration": "30"
  }
}

{
  "tool": "extract_clip",
  "arguments": {
    "video_path": "D:/DVRStorage/DVR/2/BackDrive-20250907172817356-20250907182817356.mp4",
    "start_time": "943",
    "duration": "30"
  }
}

Step 3: Combine clips into side-by-side layout

{
  "tool": "combine_videos_side_by_side",
  "arguments": {
    "input_files": [
      "D:/DVRStorage/Clips/1/videoclip-20250907134400000-20250907134428067.mp4",
      "D:/DVRStorage/Clips/2/videoclip-20250907134400000-20250907134426082.mp4"
    ],
    "output_path": "D:/DVRStorage/MultiClips/synchronized-frontdrive-backdrive-50min-ago.mp4",
    "layout": "horizontal"
  }
}

Result: A synchronized split-screen video showing both cameras at exactly the same time period.

Synchronization Best Practices

  1. Calculate Precise Time Offsets: For perfect synchronization, calculate the exact second offset from each DVR file's start time to your desired timestamp.

  2. Use Identical Target Times: Ensure both clips start at the exact same real-world timestamp (e.g., 13:44:00).

  3. Account for Camera Time Differences: DVR cameras may have slight time differences (e.g., 31-second offset between FrontDrive and BackDrive).

  4. Verify Timestamps: Check the extracted clip timestamps to confirm synchronization before combining.

Sequential Video Stitching Workflow

Creating Continuous Timeline from Multiple Clips

Step 1: Extract sequential clips from the same camera

{
  "tool": "extract_clip",
  "arguments": {
    "video_path": "D:/DVRStorage/DVR/1/FrontDrive-20250907172746904-20250907182746904.mp4",
    "start_time": "0",
    "duration": "30"
  }
}

{
  "tool": "extract_clip",
  "arguments": {
    "video_path": "D:/DVRStorage/DVR/1/FrontDrive-20250907172746904-20250907182746904.mp4",
    "start_time": "30",
    "duration": "30"
  }
}

{
  "tool": "extract_clip",
  "arguments": {
    "video_path": "D:/DVRStorage/DVR/1/FrontDrive-20250907172746904-20250907182746904.mp4",
    "start_time": "60",
    "duration": "30"
  }
}

Step 2: Stitch clips into continuous sequence

{
  "tool": "stitch_videos",
  "arguments": {
    "input_files": [
      "D:/DVRStorage/Clips/1/videoclip-20250907172746904-20250907172816904.mp4",
      "D:/DVRStorage/Clips/1/videoclip-20250907172816904-20250907172846904.mp4",
      "D:/DVRStorage/Clips/1/videoclip-20250907172846904-20250907172916904.mp4"
    ],
    "output_path": "D:/DVRStorage/MultiClips/continuous-90-second-sequence.mp4",
    "method": "concat"
  }
}

Result: A seamless 90-second video combining three 30-second clips.

Natural Language Examples for LLM Training

User Request: "Create a side-by-side video from both cameras starting 30 minutes ago for 1 minute"

LLM Response Pattern:

  1. Calculate target time (current time - 30 minutes)
  2. Find DVR files covering that time period
  3. Calculate precise offsets for each camera
  4. Extract synchronized clips
  5. Combine using side-by-side layout

User Request: "Show me what happened at 2:15 PM on both cameras"

LLM Response Pattern:

  1. Find DVR files covering 2:15 PM
  2. Calculate offsets from file start times to 14:15:00
  3. Extract clips from both cameras
  4. Combine with horizontal layout

User Request: "Create a 5-minute continuous video starting from 1:30 PM"

LLM Response Pattern:

  1. Find DVR files covering 1:30 PM timeframe
  2. Extract multiple sequential clips (e.g., 5 x 1-minute clips)
  3. Use stitch_videos to create continuous timeline
  4. Verify seamless playback

User Request: "Stitch together clips from 2:00, 2:15, and 2:30 PM"

LLM Response Pattern:

  1. Extract individual clips from specified times
  2. Use stitch_videos with "filter" method for potential format differences
  3. Create chronological sequence

Error Handling

The server includes comprehensive error handling:

  • FFmpeg availability checks
  • File existence validation
  • Natural language parsing fallbacks
  • Detailed logging for troubleshooting

Logging

The server uses Python's logging module with DEBUG level by default. Logs include:

  • FFmpeg command execution
  • File parsing results
  • Error details and stack traces
  • Natural language parsing attempts

Cross-Platform Compatibility

The server is designed to work on both Windows and Linux:

  • Uses os.path.join() for path handling
  • Checks FFmpeg availability on startup
  • Handles different path separators automatically

License

This project is open source and available under the MIT License.