LeClap

@leclap/mcp

Connect your AI agent to LeClap’s video engine. Discover samples, author a template, validate it, inspect real frames, revise and render. Start with the agent guide.

An MCP server that exposes the ffmpeg-video-composer engine as agent-callable video tools.

An AI agent (Claude Desktop, Cursor, …) is the LLM; this server helps it author a customized template with nice effects from the schema, then validates and renders it deterministically to an mp4. The server includes the 50 showcase samples through the shared packaged catalog, with creative direction, descriptors and required inputs. It works without the app or private creative-kit at runtime. Remotion-assisted authoring is an optional path. The result is _agent-composable, deterministic, reproducible_ video — the opposite of generative video models, which sample rather than render.

Tools

analyze_sound seeds a sound's noise and jitter with seed (default 0). To hear the exact render a template will play, pass the template's global.seed as seed and the cue's path as cue: "sections.intro.sfx[0]" for the first cue of the section named intro, "global.sfx[2]" for the third global cue. The tool then seeds the sound as the mix seeds that cue and returns the seed it used. Levels are floored at -120 dBFS, so a silent sound reads -120 and raises sound_silent.

Typical agent flow: get_samples → get_samples { id } → inspect requirements and customize media/copy → get_template_schema → validate_template (iterate until valid) → render_frames (look at the result; check safe zones with safe) → compose_video → read the returned outputPath. Author a fresh descriptor from the schema when no sample fits.

render_frames renders through a per-section cache under /.section-cache, so a second look after a small edit re-encodes only the sections that changed. It runs in the render worker under the same media-dir checks, slot cap, timeout and cancellation as compose_video, writes PNGs to /frames- /, and inlines at most eight images (the sheets when sheet is set). Moments are seconds or time references on the whole video: "intro.end" (a section or an element id), "50%", "beat:8", "cue:drop + 0.1". validate_template with include: ["timeline"] lists the moments worth picking.

validate_template also reports, render-free, text that would run off the frame or out of title-safe, collide with other text, sit under a band, be too small, lack contrast, or sit over footage with no box, outline or shadow. Those findings arrive on the optional geometry field — one line each, saying what to change, and the field is absent entirely when there is nothing to fix. They are advisory: valid stays true. A line ending (approx: …) says why it is an estimate: the font could not be read, the text carries a {{ variable }} that only resolves at render time, or a section declares no duration. When a font is not bundled, the server fetches it from the LeClap asset catalog (5s timeout); offline, it estimates.

Pass render: true to validate_template to also render the sections that hold text and measure their contrast from real pixels — it settles text over images, grades and looks that the render-free check can only call unknown. It costs seconds (two renders of those sections), goes through the same media-dir sandbox as compose_video, reads assets from the media dir, and runs in the same forked render worker under the same timeout. It adds a render field (measured, seconds, and unavailable when it could not render — no FFmpeg with drawtext, a failed render, or a timeout); the render-free findings come back either way.

Discover samples before authoring

get_samples is always available, even with Remotion disabled. It reads packaged data only: no media downloads, effect execution or repository access. Without id it lists, filtered by optional category (templates, typography, effects, app-demos, overlays, evidence), backend (native, remotion) and case-insensitive query (up to 4000 characters). With id (1–200 characters) it returns that sample.

{ "name": "get_samples", "arguments": { "category": "app-demos", "backend": "native" } }

{ "name": "get_samples", "arguments": { "id": "web-app-promo" } }

Results include identical JSON in text and structuredContent; with id, the descriptor sits at template alongside its metadata. Unknown IDs return isError with a discovery hint. Required inputs include named clips and durations/capture hints, form fields and limits, variables/defaults/placeholders, assets, effective preset font files (source: "preset") and versioned effects. Replace the sample copy, supply clips by userVideoPaths and form values by fields, customize global.variables, then pass template to validate_template and compose_video. Referenced partials are embedded in the descriptor.

The 25 native samples use FFmpeg; the 10 registered effect samples require --allow-remotion, Remotion peers and a trusted --remotion-entry. Effects with customCatalog: true also require the operator's --effect-catalog and the matching composition in that entry. Sample discovery does not enable execution, install a catalog or supply React source. Inspect requirements.setup and, after operator setup, get_effect_schema before editing effect props. See operator catalogs.

Pr