Skip to main content
Glama

Local Video Scenes MCP

Local Video Scenes MCP extracts timestamped screenshots from local videos so Claude can produce a visual walkthrough. It does not use Whisper, audio transcription, or any hosted video-processing service.

What Stays Local

  • The original video stays on your machine.

  • ffmpeg and ffprobe run locally.

  • The MCP returns local screenshot paths and metadata.

  • Claude analyzes only the screenshots you provide through the MCP result.

  • Audio is not extracted or analyzed in V1.

Related MCP server: Video MCP Server

Requirements

  • Node.js 18.18+

  • ffmpeg and ffprobe

The server includes video.check_ffmpeg, which reports whether ffmpeg/ffprobe are available and gives platform-specific install guidance. It also includes video.install_ffmpeg, which dry-runs by default and only runs package-manager commands when called with execute: true.

When a package manager is detected, it suggests commands such as:

brew install ffmpeg
winget install --id Gyan.FFmpeg -e
choco install ffmpeg -y
sudo apt-get install -y ffmpeg

MCP Configuration

After installing or building the package, configure your MCP client to run:

{
  "mcpServers": {
    "local-video-scenes": {
      "command": "npx",
      "args": ["local-video-scenes-mcp"]
    }
  }
}

For local development from this repository:

{
  "mcpServers": {
    "local-video-scenes": {
      "command": "node",
      "args": ["/absolute/path/to/local-video-scenes-mcp/dist/server.js"]
    }
  }
}

Tools

video.extract_scenes

Input:

{
  "path": "/path/to/bug-demo.mp4",
  "sensitivity": 0.3,
  "minGapSeconds": 1.5,
  "mode": "auto"
}

Optional fields:

  • sensitivity: scene-change threshold between 0 and 1; default 0.3.

  • maxFrames: maximum returned frames; default min(80, max(12, ceil(durationSeconds / 3))).

  • minGapSeconds: minimum gap between returned frames; default 1.5.

  • outputDir: output folder; default is a temp folder.

  • mode: auto, scene, or sample; default auto.

Output includes:

  • duration

  • sourcePath

  • outputDir

  • extractionMode

  • maxFrames

  • performanceEstimate

  • warnings

  • frames[] with timestamp, path, index, and optional sceneScore

video.cleanup

Removes the generated frame directory:

{
  "outputDir": "/tmp/video-context/abc123"
}

video.check_ffmpeg

Checks local ffmpeg/ffprobe availability and returns install guidance if either is missing.

video.install_ffmpeg

Returns the detected install commands by default:

{
  "execute": false
}

To run the detected package-manager command, call it explicitly with:

{
  "execute": true
}

Performance Defaults

The default frame budget is tuned for 1-minute screen recordings:

maxFrames = min(80, max(12, ceil(durationSeconds / 3)))

For a 60-second video, this returns about 20 frames by default. On an M2 with 16GB RAM, expected V1 behavior is:

  • ffmpeg extraction: usually 1-5 seconds

  • Claude visual walkthrough over 12-25 screenshots: roughly 10-30 seconds

  • target end-to-end time for a 1-minute video: under about 30 seconds in normal cases

Claude Usage Guidance

When a user provides a video path:

  1. Call video.extract_scenes.

  2. Inspect the returned image paths as visual context.

  3. Produce a timestamped walkthrough of visible UI states, actions, errors, code, logs, and important text.

  4. Mention that audio was not analyzed.

  5. Use video.cleanup when the generated screenshots are no longer needed.

Example:

The video shows the user opening the dashboard, navigating to Export, clicking the export action, and reaching a visible HTTP 500 error around 00:01:42. Audio was not analyzed.

Development

npm install
npm test
npm run typecheck
npm run build

Available Tools

4 tools
video.check_ffmpegCheck ffmpegA

Check whether ffmpeg and ffprobe are available and return install guidance if not.

Inputs: no named parameters.

video.cleanupCleanup Video FramesB

Remove a generated video scene output directory.

Inputs: outputDir (required).

video.extract_scenesExtract Video ScenesA

Extract timestamped local screenshots from a video using ffmpeg scene detection with fallback sampling. Audio is not analyzed.

Inputs: path (required), mode, maxFrames, outputDir, +2 more.

video.install_ffmpegInstall ffmpegA

Return or run detected ffmpeg install commands. Dry-run by default; pass execute: true to run package-manager commands.

Inputs: execute.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: checking availability, installing, extracting scenes, and cleanup. No overlap in functionality.

    Naming Consistency5/5

    All tools use a consistent 'video.' prefix and snake_case. The pattern verb_object (e.g., check_ffmpeg, extract_scenes) is maintained throughout.

    Tool Count5/5

    Four tools adequately cover the essential workflow for a video scene extraction server: environment check, installation, extraction, and cleanup. The scope is well-balanced.

    Completeness4/5

    The tool surface covers the core operations (check, install, extract, cleanup). A minor gap is the lack of a read-only tool to list previously extracted scenes without re-running extraction, but overall it's sufficient.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude Code, Codex, Claude Desktop and Cursor to see and hear MP4/MOV/MKV/WebM videos and screen recordings through timestamped keyframe storyboards, zoom and full-resolution frame drill-down, and a locally generated Whisper transcript. It also works with recording bundles that capture clicks and typed context, and runs entirely on the user's machine with no uploads or API keys.
      5
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an agent to process local video files and then read, search and inspect the results: timestamped transcripts, on-screen text and key frames as images. Everything runs locally, so an agent can answer questions like how to perform a task shown in a screencast or meeting recording.
      379 npm
      1
      MIT