FilmCraft MCP with Claude Code: Setup Before Real Edits

FilmCraft MCP connects Claude Code to an actual video-editing engine, rather than stopping at suggested shell commands. FilmCraft exposes its editing actions as named commands, and its MCP server lets Claude import media, manipulate a timeline, inspect frames, and export the result. My interest is in making repetitive editing work reviewable—not in handing an agent an important project and hoping the output looks right.

The source walkthrough describes FilmCraft as alpha software. That is the qualification I would carry into every adoption decision here. I would try it on disposable projects before considering it for an editorial workflow.

Why I care about FilmCraft's command model

The important design choice is that FilmCraft's interface, command-line tool, JSON control channel, and MCP server dispatch the same engine commands. Each command has an identifier, typed parameters, and an enabled state. The source lists 701 commands in version 0.12.0; I would treat that as the documented snapshot, not a guarantee about whichever build I install.

For example, cutting a sequence uses timeline.razor. Applying an effect uses effects.apply. I prefer this model to starting with coordinate-based clicking because it gives me an explicit operation and parameters to inspect.

FilmCraft also exposes project and sequence inspection tools, plus frame rendering. That gives me a useful review pattern: inspect the current state, make a bounded edit, then inspect the result. The source says edits enter the undo history, including individual steps inside a command batch.

That is the part I would test first around newsroom video CMS work. I would want repetitive preparation separated from editorial decisions, with a person checking the chosen footage, timing, and titles before an export is accepted.

Should I use FilmCraft bridge mode or headless mode?

I would start with bridge mode. It connects the MCP server to the FilmCraft window on my screen, so I can watch changes and correct them. Headless mode runs an editing engine without that window and is the source's suggested option for batch jobs and scripted exports.

The distinction matters because the two modes do not share the same working context. Bridge mode edits whichever project is open in the connected window. A headless engine starts with an empty project. I would make project identity an explicit checkpoint rather than assume the agent is working on the intended material.

For my first evaluation, visibility wins over unattended operation. I would consider headless processing only after I had a narrowly defined recipe, known inputs, and a review process. I would also ask the agent to save headless work with file.saveAs before ending the session, as the walkthrough advises.

Connecting FilmCraft to Claude Code in bridge mode

Check the local programs before registering anything

I would install FilmCraft and Claude Code using their documented distribution routes, then verify that both command-line programs are available. FilmCraft provides builds for Windows, macOS, and Linux; the following checks and listener command follow the source's Linux setup.

claude --version
filmcraft-cli --version
which filmcraft-cli

I would keep the printed CLI path handy. The source notes that applications may not inherit the same search path as a terminal. If launching the server fails because the executable cannot be found, I would use its full path rather than change unrelated settings.

Register one server with an explicit scope

Claude Code supports local, project, and user scopes. I would choose local scope for a contained experiment, user scope for a personal editor setup used across folders, and project scope only when I intentionally want a shared repository configuration. The walkthrough's user-scoped bridge registration is:

claude mcp add --scope user filmcraft -- filmcraft-cli --bridge 127.0.0.1:7878 mcp

Everything after the double dash is the command Claude Code launches. I would not start another MCP server manually for normal use: Claude Code starts that child process and communicates with it through standard input and output.

For a team repository, I would review a project-defined server configuration as executable setup, not merely documentation. The source says Claude Code asks for approval when it first encounters a project-defined server. I would use that checkpoint to inspect the command and arguments.

Open FilmCraft with its control channel enabled

This is the connection detail I would put directly in a team runbook. Opening FilmCraft normally is not enough for bridge mode. The window must be started with its control port enabled, and that port must match the registered bridge address.

filmcraft --control 7878

# In another terminal on Linux:
ss -ltn | grep 7878

If FilmCraft is already open without the flag, I would save the project, close the application, and reopen it correctly. I would avoid changing the desktop launcher until the terminal-based setup works. That keeps the initial troubleshooting surface small.

Restart Claude Code, then test the whole chain

Claude Code loads MCP servers when a session starts. After registration, I would start a fresh session and check the configuration:

claude mcp list
claude mcp get filmcraft

A connected status proves that Claude Code reached the MCP server. It does not prove that the server can reach the FilmCraft window: the bridge connects to the application when a tool is used. My first request would therefore be read-only: Use the FilmCraft tools to tell me what state the editor is in.

The walkthrough identifies ui_inspect as the tool for this request. I would approve that call and verify the reported workspace before asking for any edits. Only then would I consider the setup tested end to end.

Testing a FilmCraft edit without trusting the whole workflow

My first editing request would be deliberately small: import a disposable clip, create a sequence with explicit dimensions and frame rate, place a short segment, and render a frame for inspection. I would specify those choices rather than ask for something vague like “make it social-ready.”

I would ask Claude to inspect the project and sequence before changing them. The source's examples show imports and sequence creation returning identifiers that later commands use. I would not copy those example identifiers into another project; I would require the agent to use the values returned by the current session.

Timing deserves similar care. FilmCraft uses ticks internally, although the source says most commands also accept seconds, frames, or timecode. I would prefer those readable units where the command supports them and ask the agent to inspect command parameters before constructing unfamiliar operations.

My review gates would be simple:

1. Confirm the open project and intended sequence before mutation.
2. Inspect the timeline after placing or trimming media.
3. Render frames at points where titles, crops, or effects change.
4. Review a preview before approving the final export.
5. Save the project explicitly rather than treating an exported file as the only deliverable.

Those are my proposed operating rules, not guarantees supplied by MCP. Frame rendering lets the agent examine an image; I would still make a human responsible for accepting the finished video.

Debugging FilmCraft by the broken connection

I would troubleshoot this as separate links: Claude Code to the MCP process, then the MCP process to the editor. If tools are missing, I would check registration and restart the Claude Code session. If the server cannot launch, I would check the CLI path.

If the server appears connected but reports a refused connection to 127.0.0.1:7878, I would check how FilmCraft was launched and whether the port matches. Reinstalling Claude Code would not be my first response to an editor-side connection failure.

If edits reach the wrong project, I would inspect the open window. That is a workflow problem the source explicitly calls out, not evidence that another server registration is needed.

What FilmCraft MCP does not solve

I would not confuse undo history with a complete approval policy. It makes editing changes reversible inside FilmCraft; it does not tell me whether a cut preserves context or whether a title is editorially appropriate. Those remain review decisions.

Claude Code asks for permission before MCP tool calls by default. The source explains how to allow the entire FilmCraft server, but I would retain individual approvals during evaluation. Less interruption is attractive only after I understand which operations I am authorizing.

I would also ignore MCP initially if my requirement were just inspecting a saved project or exporting an existing sequence. The CLI already supports inspection, frame rendering, and export. I would choose that smaller interface for a fixed task, and consider JSONL command scripts for recipes I want to review and rerun.

My adoption threshold is straightforward: demonstrate one repetitive editing task on disposable material, inspect the saved project and output, then decide whether agent-driven interaction adds enough value. Until that works predictably in my own checks, I would keep FilmCraft's alpha status visible and keep important editorial work outside the experiment.