fcpkit-mcp
Provides tools for interacting with Final Cut Pro timelines and libraries, enabling checks, edits, and guarded imports into Final Cut Pro via AppleScript and Apple events.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fcpkit-mcp brief MyTimeline.fcpxmld and check its transition handles"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
fcpkit-mcp
Exact, safety-first tools for Final Cut Pro timelines (FCPXML) on macOS.
fcpkit reads .fcpxml files and .fcpxmld bundles with exact rational time,
resolves what every clip really shows and plays — through multicam angles,
compound clips, sync clips and retimes — and uses that to check the
things FCP gets wrong silently: transitions that run past the media,
dissolves over jump cuts, effects and templates that will go missing on import,
media that will not relink. A guarded importer puts an XML into the library
you name, and nowhere else.
Python 3.9+, standard library only.
ffmpegis needed only for pictures and loudness.Never overwrites a source. Every write goes to a new file, is validated against the FCP DTD that ships inside your Final Cut Pro, and is refused if the source changed since it was read.
Unknown is REVIEW, never PASS. A mapping fcpkit cannot resolve exactly is reported as such; exit code 2 means "could not verify".
Status: alpha (0.1.0). Developed against Final Cut Pro 12.3 and 12.4 on macOS, FCPXML 1.11–1.14.
Install
pip install . # from a checkout (installs the fcpkit-* commands and fcpkit-mcp)Every tool is also runnable as a module: python3 -m fcpkit.handles X.fcpxmld.
Related MCP server: final-cut-pro-mcp
Tools
Exit codes for the checkers: 0 pass, 1 defect found, 2 could not verify (REVIEW).
Read first: the brief
fcpkit-brief X.fcpxmld [--from 60 --to 120] [--detail 1|2|3] [--lang en|ko] [--out brief.md] [--json rows.json]
Raw FCPXML is machine detail — ids, rational times, text-style definitions, effect blobs, bookmarks. Reading it costs a model (or a person) a lot of time and things get missed. The brief "decompiles" it into the edit:
a symbol table: every source / multicam / compound becomes
M1, M2 …, every template or effectT1, T2 …, so long names appear once;one line per main-storyline cut —
▌00:07.01 M1 @05:36.90 [angle] vol -15dB (1.94s)— and under it everything that starts during that cut: captions and titles with their text, overlays, sounds, music, transitions, markers, with lane, time, length and key values (volume, scale/position, effects, speed, keyframes);values shared by most cuts are stated once in the header, not repeated;
a compound clip on the main storyline is opened: its inner cuts appear as normal lines in timeline time (nested compounds too); compounds used as overlays stay one line with the number of items inside, and the coverage line reports that number separately;
a lane table, per-minute density, and a coverage line:
timed items shown 1413/1413 (all)— anything not shown is named.
On two real 15-minute multicam/longform timelines: 1.52 MB → 69 KB and 1.16 MB → 61 KB, every timed item shown. --json keeps exact rational times and the XML path of each row, so you can go from a brief line back to the element. Over MCP this is fcpkit_brief — have the agent call it before reading any XML.
Edit through the brief. fcpkit-brief X --ids --out X.brief.md numbers every element line (#n) and records the XML's sha256. Edit the brief — move a caption, change its length, lane or text, change vol -12dB, delete a line — and run fcpkit-brief-apply X X.brief.md --out X_fixed.fcpxmld (MCP: fcpkit_brief_apply). Only changed lines are applied, to the exact element each #n stands for: times snap to frames; an item moved past its host clip is re-anchored to the main-storyline clip at the new time, in the position the FCP DTD requires; a text change touches only the styled run that holds it. Main-storyline cuts accept only volume (anything else would ripple). New lines, other value changes, keyframed volumes and text edits that span differently styled runs are refused, and then nothing is written. After applying, every element is compared before/after — only the edited ones may differ, each to the requested value — and the result is DTD-validated and written as a new file. A range brief (--from/--to) can be applied too. Same-lane overlaps caused by an edit are reported as warnings. Live check on Final Cut Pro 12.3: six edits to a 15-minute timeline (text, nudge, re-anchor, volume, delete) imported without warnings, and FCP's own export matched the applied XML item for item.
Checks (read only)
Command | What it does |
| For every transition (main storyline and connected storylines) measures where it really sits — FCP exports off-centre transitions — and whether each side has the media it needs, resolving multicam angles, compounds and linear retimes. Classifies the cut as jump (same source, time jumps), continuous, different source, or fade. A dissolve over a jump cut shows the material the cut removed → FAIL. |
| A row of frames + waveform (red ticks = cuts) of the main storyline around a timeline time, each frame resolved through angles/compounds. |
| Checks every |
| Where each asset's media lives, whether it exists now (NFC/NFD-aware: Korean, Japanese and accented names come in both forms), whether it carries a bookmark, grouped by volume; with |
| What changed between two timelines, e.g. your generated build and the editor's FCP export. Matching runs in stages from most to least certain (identical → same text → same source in-point → same placement → most-overlapping source range) and only pairs keys that are unique on both sides. Reports frame deltas of start/end/source, lane and text changes, added/removed items, grouped by kind. |
| The shared base: every timed element with absolute start/end and lane; |
Edits (always to a new file)
Command | What it does |
| Moves caption / zoom starts back onto a main-storyline cut when the cut is at most |
Final Cut Pro (live) and safety rails
Command | What it does |
| Which FCP copy is running — identified by executable path, because several copies (stock, an older version, a SpliceKit-patched copy) share the bundle id |
| Imports into the library you name, guarded. It writes an import copy whose first child is |
| Binds an approval to one exact job: plan id = sha256 of (action, XML content hash, library, event, app, validity window). A rebuilt XML, another library or an expired window → refused. |
| Append-only write ledger (JSONL) with input/output sha256 (bundles hashed whole). Undo never deletes: it moves outputs into |
| Waits for a fresh FCP "Export XML" by content hash (stable across two polls, newest wins) and optionally diffs it against your build. |
| MCP server (see below). |
Import checks, all before any Apple event: lock file free; plan id matches;
every /Volumes/<name> holding media is mounted; exactly one FCP running and
it is the planned app; target library is open in FCP (path match is case-,
slash- and NFC/NFD-insensitive); no open library modified in the last 10
minutes (someone may be editing); no event of the same name in the target
library; no FCP dialog already open; the copy does not exist yet.
Behaviour verified live on Final Cut Pro 12.3
Observed with a scratch library while building the importer (not inferred):
Situation | What FCP did |
| Imported exactly there; projects visible in the listing within ~10 s. |
Library location does not exist | FCP silently created a new library at that path and imported into it — hence the "must be open" check ( |
The XML also contains |
|
A 30-frame transition whose clips have only 6 frames of handle | Imported without any warning, shortened to 6 frames — the maximum |
AppleScript | Cannot be coerced to text (error −1700). fcpkit reads every field in its own |
Two FCP copies installed (12.3 and 12.4) | Same bundle id; |
Known from earlier use or other sources, and guarded against, but not re-tested here:
without <import-options> a flat .fcpxml imports nothing silently and a
.fcpxmld opens a blocking "which library?" picker; importing an event whose
name/uid already exists in the library fails with "Invalid argument"
(fcpkit refuses before sending anything).
Not yet verified: stock FCP 12.4 import behaviour, recording of real warning dialogs (missing media), XML files over 1 MB.
Configuration
Defaults suit a stock install; override with environment variables (most also have a CLI flag).
Variable | Default | Used by |
|
| the app |
| — ( | extra FCP copies to recognise; a SpliceKit copy in |
|
| cooperative lock while a tool drives FCP ( |
|
| optional SpliceKit bridge, read only, for dialog recording |
|
| filmstrips, loudness |
|
|
|
|
| which title templates |
Safety model
Sources are never overwritten. Writes go through
fcpxml_io: the bytes outside the<fcpxml>root (declaration, DOCTYPE) are kept byte-for-byte, the re-serialised tree is re-parsed and compared, the result is validated withxmllintagainst the DTD inside your installed Final Cut Pro, the output must not exist (exclusive create), and the source is re-hashed just before publishing.Unknown is REVIEW, not PASS. Unsupported retimes (holds, reverse, eased multi-point ramps), unresolved references, missing registries — all surface as REVIEW with the reason.
Live steps are opt-in and bounded. Nothing launches FCP implicitly. An import needs an approved plan id, takes a lock, refuses on any failed check, and leaves a receipt. Lock files are renamed, not deleted, when released.
Undo moves, never deletes, and only files whose hash still matches.
Hostile files are refused, not expanded. FCPXML never uses entities, so any
<!ENTITY>or DOCTYPE internal subset is rejected before parsing (old expat builds, such as the one in macOS's/usr/bin/python33.9, have no entity-expansion limits). External entities are never fetched;xmllintruns with--nonet. No tool runs a shell: every subprocess gets an argument list, and the only value put into AppleScript (the FCP app path) is escaped.
MCP server (read only, except filmstrip pictures)
fcpkit-mcp speaks MCP over stdio (stdlib only) and exposes fcpkit_brief, fcpkit_brief_apply, fcpkit_handles,
fcpkit_effects_check, fcpkit_timeline_diff, fcpkit_relink_preview,
fcpkit_filmstrip (returns the PNGs as images) and fcpkit_libraries. It has
no tool that writes XML or imports into FCP.
claude mcp add fcpkit -- fcpkit-mcpHow it compares with fcp-mcp-server
DareDev256/fcp-mcp-server is a broad MCP server for driving FCP (editing, assembly, transcription, automatic import). Several fcpkit tools started from ideas found while reading it (v0.27.2): <import-options> targeting, AppleScript library listing, handle checks, filmstrip + waveform, effect registry lookup, the write journal. fcpkit is narrower and differs in emphasis:
fcpkit | fcp-mcp-server (v0.27.2, code read, not run) | |
Scope | checks, a few guarded edits, guarded import | wide editing and automation surface |
Multicam / sync clips | resolved to the active angle, separately for video and audio |
|
Time | exact | frame rate from the first |
Unknown cases | REVIEW with a reason | unresolvable clips are skipped |
FCP behaviour evidence | observed live on FCP 12.3 (above) | tests simulate |
Pick fcp-mcp-server when you want an agent to edit broadly; pick fcpkit when you want to know, exactly, whether a timeline will survive the trip into FCP.
Tests
python3 -m unittest discover -s testsAll tests use synthetic XML and ffmpeg-generated media; none sends an Apple
event or opens FCP (the live import flow runs against fakes). FCPKIT_TEST_TMP
sets where temporary files go. One test compiles the listing AppleScript with
osacompile and is skipped when no Final Cut Pro is installed.
License
MIT — see LICENSE.
Available Tools
8 toolsfcpkit_briefARead-only
Read a timeline as a compact editorial brief instead of raw XML (call this first): symbol table of sources/templates, one line per main-storyline cut (source @time, angle, non-default volume/scale/effects) and under it every caption (with text), title, overlay, sound, transition and marker that starts during that cut; lane table, density, and a coverage line "timed items shown n/n". Typically 15-25x smaller than the XML.
Inputs: xml (required), end, ids, lang, +2 more.
fcpkit_brief_applyA
Apply an edited brief (made with fcpkit_brief ids=true from this exact XML) back to a NEW FCPXML: only changed lines are applied — start time, length, lane, caption text, "vol NdB", or a deleted line; main-storyline cuts accept vol only. Anything else is refused and nothing is written. The result is verified (only the edited elements changed, to the requested values) and DTD-validated. Never overwrites the source.
Inputs: out (required), xml (required), edited_brief (required), dry_run, +1 more.
fcpkit_effects_checkARead-only
Check that every resource resolves: Motion templates (src/uid files), FCP built-in templates, FxPlug UUIDs against FCP's own registry and installed plug-ins. MISSING/REVIEW/OK/INFO per effect.
Inputs: xml (required), templates_dir.
fcpkit_filmstripB
Pictures of the main storyline around timeline times: evenly spaced frames resolved through multicam angles/compounds, waveform underneath, red ticks at cuts. Writes PNGs to a new folder and returns them as images (max 8 times).
Inputs: at (required), xml (required), pre, post, +2 more.
fcpkit_handlesARead-only
Check every transition: does each side have the media it needs (multicam, compound and retime aware), and does a dissolve sit on a jump cut (it would show removed material)? Statuses PASS/INFO/REVIEW/FAIL; unknown is REVIEW, never PASS.
Inputs: xml (required), measure.
fcpkit_librariesARead-only
List the libraries, events and projects open in the running Final Cut Pro (AppleScript, read only). Refuses if FCP is not running or two copies run; never launches FCP.
Inputs: timeout, durations.
fcpkit_relink_previewARead-only
Report each asset's media path, whether it exists (NFC/NFD aware), bookmark presence, and what a whole-segment prefix remap would find. Never rewrites the XML.
Inputs: xml (required), to_prefix, from_prefix.
fcpkit_timeline_diffARead-only
What changed between two timelines (e.g. a generated build vs the editor's FCP export): unique-key matching, frame deltas of start/end/source, lane and text changes, added/removed items.
Inputs: a (required), b (required), kinds, caption_pattern.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
The tools cover distinct jobs: listing open FCP state, reading a compact brief, applying brief edits, checking transition handles, checking effects, diffing timelines, previewing relinks, and producing filmstrips. The timeline-inspection and validation tools are related but remain clearly separated by their outputs and descriptions.
All tools use a consistent fcpkit_ prefix and snake_case naming. The suffix grammar varies somewhat (noun, noun_verb, verb_noun), but names remain readable and predictable.
Eight tools is well within an appropriate range for an FCPXML inspection and editing toolkit. Each tool appears to earn its place by covering a distinct workflow step.
The surface covers listing open FCP state, timeline briefing and editing, transition/effect validation, timeline diffing, relink preview, and visual inspection. Minor gaps exist around broader project/media management and more general FCPXML write operations, but core workflows are covered.
Maintenance
Related MCP Connectors
Evidence-readiness MCP server: validate, audit, and score briefs, memos, and evidence packs.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Read-only XRP Ledger MCP tools with proof-annotation envelopes and signed daily snapshots.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Related MCP Servers
- AlicenseAqualityAmaintenanceThe first MCP server for Final Cut Pro. 53 tools that parse, edit, and generate FCPXML timelines via natural language. Health checks, flash frame detection, chapter markers, rough cuts, NLE export. 912 tests, MIT licensed.153,797 PyPI157MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that enables AI to control Final Cut Pro on macOS, including reading libraries/projects, importing FCPXML, and creating title or storyboard projects.MIT
- FlicenseNot gradedqualityAmaintenanceEnables Claude and other MCP clients to read, edit, and generate real Final Cut Pro timelines from FCPXML, including cut detection, markers, roles, silence removal, transcript-based editing, cross-NLE export, and pushing changes into a running Final Cut Pro. Every write is journaled and undoable, with validation and safety checks for reliable timeline edits.-
- FlicenseNot gradedqualityAmaintenanceEnables an MCP client like Claude to read, edit, and generate real Final Cut Pro timelines from exported FCPXML, covering cut and flash-frame detection, silence and gap removal, markers, keyframes, speed ramps, transcript-based editing, cross-NLE export, and pushing the result into a running Final Cut Pro. Every write is journaled with its sha256 so changes can be undone and unreviewed cuts refused.-