@leclap/mcp

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 ships no built-in template catalog — it is decoupled from the app's creative-kit — so it stays a generic authoring tool. Remotion-assisted authoring is a bonus path. The result is agent-composable, deterministic, reproducible video — the opposite of generative video models, which sample rather than render.

Tools

Typical agent flow: get_template_schema → author an inline descriptor (optionally prepend a render_remotion_clip intro) → validate_template (instant, iterate until valid) → compose_video → read the returned outputPath.

Bring-your-own Remotion (optional). If you have a Remotion project, render_remotion_clip renders one of its compositions — genuine motion graphics (spring physics, kinetic typography) an FFmpeg filtergraph can't express — to an mp4. Point it at your entry (the module that calls registerRoot) or a prebuilt serveUrl, plus a compositionId and optional inputProps; or set a default with --remotion-entry / LECLAP_MCP_REMOTION_ENTRY. Feed the returned clip to compose_video as a project_video clip (via userVideoPaths) and the deterministic engine composites it in front of your scenes. It needs the optional peer deps @remotion/renderer + @remotion/bundler and is design-time only (headless Chromium) — everything else in the MCP stays self-contained and on-device.

Prompt

compose-video — a guided authoring prompt (surfaces as /compose-video in clients like Claude Desktop). Takes optional goal and orientation arguments and primes the agent with the schema, the premium building-block recipes (which filters give which look, the bundled font list, the on-device filter allowlist), and the validate_template → compose_video loop.

Run

# published — no checkout needed
npx -y @leclap/mcp

# or from a checkout: build the engine + this server, then start it over stdio
pnpm --filter ffmpeg-video-composer build
pnpm --filter @leclap/mcp build
node packages/leclap-mcp/dist/index.js

It speaks MCP over stdio (stdout is the protocol channel — all diagnostics go to stderr). The published bin is leclap-mcp.

Built on the MCP TypeScript SDK (@modelcontextprotocol/server), tracking the current protocol revision. Clients on an older revision keep working — the stdio entry serves both eras from the same tool definitions.

Configuration

Each render writes to <output-dir>/<renderId>/. Local input files (userVideoPaths, probe_media) must resolve inside the media-dir (symlink-safe containment check). The media-dir default is deliberately narrow — pointing it at ~ would let any tool call read the whole home directory. render_remotion_clip executes your project's own JS, so it is registered only when the opt-in is set (--allow-remotion or LECLAP_MCP_ALLOW_REMOTION=1); leclap init --remotion scaffolds a .mcp.json with it enabled.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (absolute paths only — env values are not tilde-expanded):

{
  "mcpServers": {
    "leclap": {
      "command": "npx",
      "args": ["-y", "@leclap/mcp"],
      "env": {
        "LECLAP_MCP_OUTPUT_DIR": "/abs/path/to/Movies/leclap-renders",
        "LECLAP_MCP_MEDIA_DIR": "/abs/path/to/Movies"
      }
    }
  }
}

From a checkout, swap the command for "command": "node" with "args": ["/abs/path/to/ffmpeg-video-composer/packages/leclap-mcp/dist/index.js"].

Then ask the agent to "compose a 10-second vertical title card with a fade-in and music, then render it" — it fetches the schema, authors a descriptor, validates it, and renders. Open the returned outputPath. (There is no catalog to list: the server authors templates rather than serving stock ones.)

Inspector

npx @modelcontextprotocol/inspector node packages/leclap-mcp/dist/index.js

Architecture

compose_video never runs the compile in the server process. The core logs to stdout during a render (including pino writing directly to fd 1), which would corrupt the MCP JSON-RPC stream — so the render runs in a forked child worker (dist/render-worker.js) and the result returns over the IPC channel, never the child's stdout. This also gives clean error capture (the parent buffers the worker's logs), render timeouts, and DI state isolation between renders.

compose_video returns a resource_link pointing at the rendered file rather than inlining megabytes of base64 — the client opens or fetches it. Render progress is written to stderr ([compose_video] render <id> NN%), not sent as a protocol notification: the per-request log channel is deprecated in the current revision, and stdout is reserved for JSON-RPC framing.

Security is inherited from the core: FFmpeg runs via execFile (no shell); remote template URLs are SSRF-guarded (private/metadata IPs + redirects blocked, http(s) only); descriptors are safeParse-validated; local file paths are containment-checked against the media dir.

Tests

pnpm --filter @leclap/mcp test              # vitest unit tests (mocked render)
pnpm --filter @leclap/mcp test:integration  # cucumber BDD over real stdio + a real render

The integration suite spawns the built server over stdio and renders a self-contained color-card template end to end — the regression guard proving the stdio framing survives a real (pino-heavy) compile.

Not yet (future)

Streamable HTTP transport, MCP resources (leclap://templates/{name}), client-visible progress notifications, remote-URL probing, an async job API.

Part of the LeClap monorepo.