filmcraft-mcp

An MCP server that lets Claude edit video through FilmCraft, the open-source Rust editor modelled on Premiere Pro. Claude can create projects, import media, cut, trim, add transitions, titles and markers, and render an mp4. The result is a normal .fcproj file that opens in the FilmCraft desktop app.

How it drives FilmCraft (and why)

FilmCraft ships filmcraft-cli, a headless engine that runs the same 650+ commands as the GUI (exec, run, inspect, export, render, probe). This server uses that CLI (route a: an existing headless mode):

• Project file = source of truth. Each tool call runs filmcraft-cli --project p.fcproj --save exec <command> <json>. The edit lands in the .fcproj file at once, so you can open, inspect or hand off the project at any point. The CLI holds an OS lock while it saves, so concurrent calls don't lose edits.

• Export is native. FilmCraft has its own H.264 / AAC encoder, plus ProRes, DNxHR, GIF, PNG and WAV. ffmpeg is not needed to render.

• Why not FilmCraft's own MCP server? filmcraft-cli mcp exists and exposes generic tools (command_run, sequence_inspect, …). It holds the project in memory, though, and you have to save explicitly. You also have to know command ids and the tick time base (254,016,000,000 ticks per second). This server adds editor-level tools that take times in seconds and save on every call. The generic route is still available through run_command / run_batch.

Routes considered:

• (b) writing .fcproj JSON directly works (schema v17, documented in FilmCraft's docs/project-files.md), but it is brittle compared with the engine's own commands.

• (c) patching FilmCraft wasn't needed.

Related MCP server: premiere-pro-mcp

Setup

Works on macOS, Windows and Linux. You need:

• Node 18+

• Claude Code

• the FilmCraft CLI (filmcraft-cli)

• optionally, the FilmCraft desktop app, to open and watch the projects Claude edits

No Rust, Homebrew or ffmpeg is needed.

1. Get the FilmCraft CLI

Downloads are on the FilmCraft releases page. These steps were tested with v0.17.1.

On macOS, for example:

mkdir -p ~/filmcraft-cli && cd ~/filmcraft-cli && curl -LO https://github.com/storytold/filmcraft/releases/download/v0.17.1/filmcraft-cli-0.17.1-macos-universal.zip && unzip -j filmcraft-cli-0.17.1-macos-universal.zip

~/filmcraft-cli/filmcraft-cli --version

The server looks for the CLI at $FILMCRAFT_CLI, then bin/filmcraft-cli inside this package, then filmcraft-cli on PATH.

2. Register the server with Claude Code

Option A: straight from GitHub (recommended, no clone). npx downloads and builds the server. The first start on a machine takes about 30 s; later starts are instant.

claude mcp add --scope user filmcraft-edit -e FILMCRAFT_CLI=$HOME/filmcraft-cli/filmcraft-cli -- npx -y github:kanishk-gangwar/filmcraft-mcp

On Windows, set FILMCRAFT_CLI to the full path of filmcraft-cli.exe.

Option B: from a clone (to change the code, or to run the demo):

git clone https://github.com/kanishk-gangwar/filmcraft-mcp.git && cd filmcraft-mcp && npm install

npm install also builds dist/. Then run:

claude mcp add --scope user filmcraft-edit -e FILMCRAFT_CLI=$HOME/filmcraft-cli/filmcraft-cli -- node $PWD/dist/index.js

Either command writes an entry like this to ~/.claude.json:

"filmcraft-edit": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "github:kanishk-gangwar/filmcraft-mcp"],
  "env": { "FILMCRAFT_CLI": "/Users/<you>/filmcraft-cli/filmcraft-cli" }
}

To share the server with everyone working in one project, put the same block under mcpServers in that project's .mcp.json. Optional: set FFMPEG_PATH (or install ffmpeg) for the ffmpeg_* tools.

3. Check it works

claude mcp list

You should see filmcraft-edit: … ✔ Connected. Then ask Claude something like "Create a FilmCraft project at ~/Movies/test.fcproj, import ~/Movies/clip.mp4, keep 0–5 s and 10–15 s with a dissolve between them, and render ~/Movies/cut.mp4."

4. See the edit in FilmCraft (optional)

Install the desktop app from the same releases page:

Open the .fcproj Claude wrote (on macOS: open -a FilmCraft path/to/project.fcproj). If the project is already open while Claude edits it, use File ▸ Revert to load the changes. Don't save from the app while Claude is still editing, or you will overwrite Claude's changes.

Tools

Times are in seconds. Clip ids come from list_timeline and item ids from import_media / inspect_project. Every editing tool saves the project.

Demo (verified)

export FILMCRAFT_CLI=$HOME/filmcraft-cli/filmcraft-cli   # wherever step 1 put it
python3 scripts/make_sample.py samples      # 6 s numbered colour frames + beeps (Pillow)
# build samples/sample.mp4 with FilmCraft itself (no ffmpeg):
B=$FILMCRAFT_CLI; S=$PWD/samples   # run from a clone (Option B)
printf '%s\n' '{"id":"file.newProject","params":{"name":"Master"}}' '{"id":"file.newSequence","params":{"name":"Master","width":640,"height":360,"fps":30}}' | $B --save-as $S/master.fcproj run -
$B --project $S/master.fcproj --save exec file.import "{\"paths\":[\"$S/frames/f000.png\"],\"imageSequence\":true}"
$B --project $S/master.fcproj --save exec file.import "{\"paths\":[\"$S/tone.wav\"]}"
$B --project $S/master.fcproj --save exec timeline.place item=8 track=V1 time=0
$B --project $S/master.fcproj --save exec timeline.place item=9 track=A1 time=0
$B --project $S/master.fcproj export $S/sample.mp4 --range entire
node scripts/demo.mjs samples              # the edit, through the MCP server

scripts/demo.mjs connects to the server as an MCP client and runs these steps:

1. Creates demo.fcproj (640×360, 30 fps) and imports sample.mp4.

2. Places source 0–3 s and 4–6 s back to back, cutting out second 4.

3. Ripple-trims the first clip's out edge by 0.5 s.

4. Adds a 10-frame Cross Dissolve at the cut.

5. Adds a centred title on V2 for 0–2 s and a green marker at the cut.

6. Renders demo.mp4 (4.5 s, H.264 High + AAC, 135 frames, about 0.3 s to encode), a PNG frame, and demo.xml (FCP7 XML).

Open samples/demo.fcproj in the FilmCraft app (0.17.1) to see the edit.

What FilmCraft can't do headlessly (or at all, as of 0.17.1)

• GUI-only interaction: the mouse and keyboard tools (ui_click, ui_screenshot, …) need the desktop app running with --control PORT and FilmCraft's own MCP in --bridge mode. This server doesn't use them.

• Live sync with an open app: the CLI edits the file on disk. A project already open in FilmCraft doesn't reload by itself: reopen it or use File ▸ Revert. If you save from the app, you overwrite CLI edits made since it opened the file.

• .prproj: Premiere projects can't be opened. Bring them in as FCP7 XML, AAF or OTIO (import_media).

• Delivery codecs: software export is H.264 only. HEVC needs a hardware encoder (VideoToolbox on macOS, 8-bit SDR). There is no AV1 / VP9 / WebM export, so use ffmpeg_convert.

• Inputs: no DivX / Xvid, DV, camera RAW or E-AC-3. Transcode them first with ffmpeg_convert.

• Graphics in interchange: titles don't survive FCP7 XML export (FilmCraft reports this). OTIO keeps them under metadata.filmcraft.

• Speech-to-text (Transcribe) needs a CLI built with the whisper feature. The release CLI doesn't have it.

Notes

• import_media with imageSequence: true applies to every path in that call, so import audio separately.

• An image sequence imports at the app's default still rate (29.97 fps) unless you reinterpret it (clip.interpretFootage).

• Errors come back as MCP isError results carrying FilmCraft's own message, for example timeline.place failed: … no such item.