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.

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