Video Explainer MCP — Tool Usage Guide

First verify that the optional video-explainer-mcp server is connected and EXPLAINER_PATH points to the external checkout. It wraps the video_explainer CLI to synthesize explainer videos from text content.

Core Concept

This server is a synthesis companion to video-research-mcp. Research extracts knowledge; this server turns it into video. The pipeline is: content → script → narration → scenes → voiceover → storyboard → render.

Tool Selection Guide

Pipeline Order

Steps must run in order. Each step depends on the previous step's output:

1. script      — Generate video script from input content
2. narration   — Convert script to narration text
3. scenes      — Generate scene descriptions
4. voiceover   — Synthesize speech audio (TTS)
5. storyboard  — Create visual storyboard
6. render      — Combine into final video

Use explainer_generate to run all steps, or explainer_step for one at a time.

Content Injection

Before running the pipeline, inject content:

explainer_create(project_id="quantum-computing")
explainer_inject(
    project_id="quantum-computing",
    content="# Quantum Computing\n\nKey concepts:\n- Superposition...",
    filename="research.md"
)

Content can be:

• Research output from research_deep
• Video analysis from video_analyze
• Any markdown or plain text

Background Render Pattern

For long renders (1080p, 4K), use the start/poll pattern:

# Start render in background
result = explainer_render_start(project_id="my-video", resolution="1080p", fast=False)
job_id = result["job_id"]

# Poll every 30 seconds
status = explainer_render_poll(job_id=job_id)
# Inspect status, playable, and errors; preserve cancelled, partial, and unknown results

Quality Iteration Loop

After generating the pipeline:

1. explainer_factcheck(project_id) — Inspect the report and check decisive claims against primary sources
2. explainer_feedback(project_id, "Make the intro more engaging") — Add notes
3. explainer_refine(project_id, phase="script") — Improve specific phase
4. Re-run dependent steps: explainer_generate(project_id, from_step="narration")

TTS Provider Selection

The external video_explainer CLI owns provider implementations and model settings. This wrapper passes the selected provider; inspect that checkout before assuming current model/endpoint compatibility.

Set via EXPLAINER_TTS_PROVIDER in ~/.config/video-research-mcp/.env. The wrapper accepts only mock, elevenlabs, and edge; other values fail configuration validation.

ElevenLabs Voice Settings

Set ELEVENLABS_API_KEY locally. The checked upstream tts: configuration exposes provider, voice_id, model, and output_format. Its ElevenLabs requests hard-code stability 0.5 and similarity boost 0.75; they do not read the voice/stability/speed environment variables formerly listed here. Inspect the selected external checkout before assuming additional voice controls. For direct HTTP settings, use the TTS production skill.

Production Order Documents

For complex videos, create a POD (Production Order Document) first — a structured blueprint with script, storyboard, audio direction, and visual specs. PODs live in docs/plans/ and can be used as input via /ve:explainer → "From a Production Order".

Error Handling

All tools return error dicts on failure:

{
  "error": "description",
  "category": "SUBPROCESS_FAILED",
  "hint": "actionable fix",
  "retryable": false
}

Common categories:

• EXPLAINER_NOT_FOUND — Set EXPLAINER_PATH
• PROJECT_NOT_FOUND — Check project ID with explainer_list
• NODE_NOT_FOUND — Install Node.js 20+
• FFMPEG_NOT_FOUND — Install FFmpeg
• TTS_FAILED — Check TTS provider and API key
• RENDER_FAILED — Check Remotion installation

Completion gate

A completed pipeline step or render job is not a verified video. Inspect the actual output file, duration, dimensions, frame rate, required shots, narration, and transitions. Mock TTS is a preview limitation. Keep source claims/citations through synthesis, and fact-check decisive claims against primary material. Allow one targeted repair per observed defect inside the generation budget; preserve failed/refused/missing outputs and stop on repeated infrastructure failure. Return the exact playable artifact and remaining limitations.