video-explainer-mcp

Create source-bound images, short videos and explainer projects through 39 MCP tools. The candidate provides direct HTTP image and text/frame-video APIs, local editorial planning and existing-material assembly, plus an optional video_explainer CLI pipeline for projects, narration, scenes and rendering. Stock search/download is unmounted.

Candidate 0.2.2-rc.4 (PyPI 0.2.2rc4) is not yet publication- or installation-verified. Source links target the prospective immutable v0.8.0-rc.6 tag and resolve after publication. Check PyPI before installing; use an exact source checkout while publication is pending.

Use the Dutch problem-to-solution guide to choose a route. The image and text/frame-video APIs have their own regional credentials, generation extra, pinned inputs and quote lifecycle. They use HTTP directly and require no upstream CLI. Provider access and creative quality remain unqualified. The candidate also implements durable S2V/HappyHorse modes; their input contracts and pending native/provider acceptance are documented in the video route.

The CLI pipeline requires a separate upstream checkout, provider configuration and rendering dependencies. Its pinned upstream licence grant remains unresolved; this package ships no upstream runtime. Installation and rights for that separate CLI remain operator responsibilities.

Install and configure

The server requires Python 3.11+ and uv. For direct image/video generation, follow the route setup above. The following prerequisites apply to the separate CLI pipeline. For CLI pipeline generation and rendering, install the upstream CLI in its own checkout and virtual environment, following that checkout's instructions. That pipeline expects:

• <EXPLAINER_PATH>/.venv/bin/video-explainer as an executable console script.
• The Node.js version required by the upstream checkout, plus FFmpeg on PATH.
• Upstream Remotion npm dependencies under remotion/node_modules/.
• Credentials and compatible upstream support for each provider you intend to use.

From this package directory in a source checkout:

uv sync --locked --extra dev
uv run --locked video-explainer-mcp

After publication, the wrapper can run from PyPI as a stdio MCP server. Add this entry to your client's mcpServers configuration:

{
  "video-explainer": {
    "command": "uvx",
    "args": ["video-explainer-mcp==0.2.2rc4"]
  }
}

The core npm installer does not register this companion or install the upstream renderer.

Configuration comes from the process environment and ~/.config/video-research-mcp/.env; nonempty process values take precedence:

EXPLAINER_PATH=/absolute/path/to/video_explainer
# Optional: defaults to EXPLAINER_PATH/projects
EXPLAINER_PROJECTS_PATH=/absolute/path/to/projects
EXPLAINER_TTS_PROVIDER=mock
EXPLAINER_TIMEOUT=600
EXPLAINER_RENDER_TIMEOUT=1800

Restart after changing configuration. EXPLAINER_PATH is the checkout root, not the projects directory. The CLI runs directly without a shell, receives --projects-dir, and inherits provider credentials while recursive Claude Code guard variables are removed from its child environment.

Wrapper TTS selectors are mock, elevenlabs, and edge. The default mock avoids paid TTS; other generation steps can still call paid providers. A selector is usable only if the upstream CLI supports it and its credentials are configured. Updating this wrapper does not update that checkout or add upstream provider support.

The wrapper exposes script refinement and render presets 720p, 1080p, and 4k. These choices match the supported upstream CLI contract. Pipeline steps remain script, narration, scenes, voiceover, and storyboard.

First project and render

These are MCP calls, made through your client after registration:

1. Create a project:

   explainer_create(project_id="my-video")
   

2. Add source material:

   explainer_inject(project_id="my-video", content="...", filename="research.md")
   

   filename must be a single filename inside input/. Injection replaces an existing file with the same name; preserve the original when that matters.

3. Authorize generation, then run a bounded step such as explainer_step(project_id="my-video", step="script"), or use explainer_generate for the pipeline. Inspect returned errors and outputs before continuing. force=True reruns already completed generation steps.

4. Read explainer_status and inspect the actual generated files. Review and typecheck TSX upstream, then preview scenes before rendering.

5. Inspect explainer_doctor(project_id="my-video") before rendering. It reads local Node/FFmpeg/ffprobe versions, selected Remotion packages and cached browser, the reviewed external source and project paths. It makes no provider call and installs or downloads nothing. all_ok means technical prerequisites are present; real renderer execution, runtime grants and picture/sound quality remain unverified.

6. Start a render with explainer_render_start(project_id="my-video"). Poll the returned job_id with explainer_render_poll until completed, failed or unknown. On unknown, inspect the retained job, process ownership and existing output before choosing recovery or another render. Use blocking explainer_render for a short render.

Render acceptance requires a fresh regular H264 MP4 at the exact selected CLI output path, requested dimensions, finite duration and a complete FFmpeg decode. The maximum file size is 512 MiB; probe/decode limits are 10/60 seconds. An unchanged older video or a different output path cannot satisfy the current request. The canonical storyboard path must be storyboard/storyboard.json: the selected public CLI's Node entry ignores configured alternatives. The 720p/4k output is output/final-720p.mp4/output/final-4k.mp4; 1080p uses paths.final_video, which must be a direct MP4 in output/; nested/traversal output paths are unsupported.

playability_verified reports full decoding of the exact output bytes. It does not certify actual Remotion/TTS production or picture, sound, timing and factual claims. real_renderer_verified remains false. Polling older completed jobs without a byte-bound decode receipt reports unknown and withholds the output path. Legacy full generation prepares through storyboard then uses this same render gate; it bypasses upstream mock rendering and retained-output skipping. Managed editorial generation still stops at storyboard and renders separately.

Status and recovery

explainer_status reports filesystem observations. A step file's presence does not establish its validity or publication readiness. Render jobs are durable in the configured SQLite job store. Restart preserves IDs and receipts; unavailable process ownership is reported as unknown rather than automatically rerun. Shutdown cancels and joins active render tasks and stops their CLI subprocesses.

The server prevents concurrent renders of the same project. After a failure, inspect the job error and project output before retrying. Preserve project files when upgrading the wrapper or renderer; they are separate from package installs.

Editorial plans

explainer_plan(project_id, request) works locally with EXPLAINER_PROJECTS_PATH and an existing input/evidence-packet.json; plan review needs no CLI, stdin or provider. Use create, show, revise and approve with compare-and-swap expected_revision. A full replacement plan records audience, thesis, ordered concepts/scenes, purpose, exact claim IDs, durations and explicit inclusion or rejection of every source. Revision invalidates approval and output bindings.

The project stores this authority in planning.sqlite3. Approval is editorial; unchanged source bytes and approved exact claim text are required. Managed script production rejects different narration, scene order/purpose or duration budgets. Accepted script and storyboard bytes receive video_research_plan provenance. Use show to read actual binding hashes and current status before rendering. Storyboard binding checks the exact script parent and observed scene IDs/titles/ timing; visual/audio semantics remain unverified. External model output that paraphrases approved claims is retained as a failed output and cannot be accepted.

Managed generation uses supported individual stages and stops at storyboard; render separately through durable render tools. The CLI reads config.json → paths.storyboard: declare a relative confined JSON path. Plan operations and managed generation/refinement/injection share a fail-fast SQLite transaction; a concurrent operation returns busy instead of waiting on stdin. Legacy projects without a managed plan retain their existing CLI arguments. See the repository's docs/integrations/video-planning.md for complete examples, output checks and the remaining provider/media acceptance boundaries.

Development

The RC4 candidate adds seven image/video lifecycle tools to the 32-tool CLI, planning and assembly surface. Published 0.2.2rc3 lacks those seven APIs. Source checks and synthetic fixtures do not establish paid-provider delivery or creative quality. Use explicit image finalize/poll or video poll operations; core job_status rejects generated-media jobs. From this package directory:

uv run --locked pytest tests/ -q
uv run --locked ruff check src/ tests/
uv build

Tests use temporary projects and mocked CLI processes; no paid provider calls are made. The lockfile records the development environment; pyproject.toml defines supported dependency ranges. See the root contribution guide and publishing guide for repository and release checks.