video-shot-breakdown-mcp

An MCP server for the part of video work that happens before anything is rendered: reading a finished clip as a list of shots, and turning that list back into something you can shoot or generate.

Two tools, no dependencies, standard library only.

Tools

breakdown_shots

Give it a plain-text shot list and it returns the numbers a director actually argues about:

• shot count, total runtime, average / median / shortest / longest shot
• cuts per minute and the pacing bucket (very fast → slow long take)
• camera-movement mix (static, push, dolly, handheld, crane, aerial …)
• frame totals when you pass fps
• a normalised record per shot: description, duration, movement, lens, lighting, start time

Input is loose on purpose — timecodes, inline 3s durations, or freeform lines all parse:

1. 0:00-0:04 Wide establishing shot, slow push in, golden hour
2. 4s handheld close-up on the operator's hands
3. cut to aerial drone shot over the coastline, 6s

build_remake_plan

Takes the same shot list and returns the remake:

• one generator-ready prompt per shot (camera movement + framing + description + lighting + look)
• a camera note for live-action: slider vs. gimbal vs. shoulder mount, and what to keep constant
• clip segmentation — shots longer than max_clip_seconds (default 10s) are split into generation-sized pieces, so a 24s take becomes 10 + 10 + 4 instead of a failed 24s request
• text-to-video vs image-to-video per shot, decided by has_reference_still
• a clip budget line: "N clips at ≤10s each cover 1:20 of finished runtime"

Install

pip install video-shot-breakdown-mcp

Or run straight from the checkout, without installing:

PYTHONPATH=src python3 -m video_shot_breakdown_mcp

Register with a client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "video-shot-breakdown": {
      "command": "python3",
      "args": ["-m", "video_shot_breakdown_mcp"],
      "env": { "PYTHONPATH": "/absolute/path/to/video-shot-breakdown-mcp/src" }
    }
  }
}

Cursor / VS Code MCP (.mcp.json at the project root) uses the same shape:

{
  "mcpServers": {
    "video-shot-breakdown": {
      "command": "video-shot-breakdown-mcp"
    }
  }
}

Example session

You: break down this shot list and build a remake plan for vertical short-form, 5s clips.

Tool → build_remake_plan

{
  "target_aspect_ratio": "9:16",
  "step_count": 3,
  "generation_clip_count": 5,
  "estimated_duration_seconds": 14.0,
  "pacing": "medium (narrative)",
  "steps": [
    {
      "shot": 1,
      "duration": 4.0,
      "prompt": "camera push, wide framing, wide establishing shot, golden hour lighting, cinematic",
      "camera_note": "use a slider or gimbal, keep the move the same speed for the whole take; match the wide framing",
      "generate_with": "text-to-video",
      "clips": [{ "segment": 1, "seconds": 4.0, "shots": [1] }]
    }
  ],
  "notes": ["generator budget: 5 clips at <= 5s each cover 0:14 of finished runtime"]
}

Why not just ask a model to describe the video?

Description is the easy half. The hard half is reproducibility: what lens, what move, what light, and how long each piece may be before a generator starts drifting. This server keeps that as data — JSON you can diff, version, and feed to the next step — instead of prose.

If you want the frame-accurate version against a real video file (camera movement, lighting, and the likely production method per shot, with a remake plan attached), that is what Rea Video does locally on your own footage. This repo is the lighter, API-shaped sibling you can wire into an agent.

Downstream, the plan maps cleanly onto two generators:

• Pavo AI — text-to-video and image-to-video with consistent cast, good for the short-drama shots the plan produces
• Wan 3.0 — cinematic text-to-video / image-to-video, which is where the segmented 5–10s clips go

Tests

PYTHONPATH=src python3 -m unittest discover -s tests -v

License

MIT