The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Fcp Mcp — Final Cut Pro MCP Server listing page.
Trusted, local, human-approved Final Cut Pro workflows. fcp-mcp inspects, generates, and transactionally edits FCPXML, then optionally hands verified artifacts to Final Cut Pro. The default profile never performs direct live or offline mutation.
Version 0.3.0 freezes a 94-tool catalog across four profiles. It is a bounded FCPXML interchange and tested Final Cut Pro handoff surface—not a claim of complete autonomous Final Cut Pro control. The default workflow is inspect, prepare, review, hash approval, then commit.
Start here:
$PATH (for media_* tools): brew install ffmpegcompressor_* tools)Install the current published release from PyPI:
Or from source (for contributors):
doctor exits 0 when ready, 1 when offline service is usable but
optional capabilities are degraded, and 2 when configuration blocks
required runtime behavior. MCP clients can call the same structured
surface through fcp_doctor.
Or if you installed from source, point at your venv's Python:
Or edit ~/.claude.json directly:
Add the same config to your Claude Desktop config file:
~/Library/Application Support/Claude/claude_desktop_config.jsonSelect a profile with FCP_MCP_PROFILE. The default workflow profile keeps
the inspect → prepare → review → hash approval → commit sequence bounded and
reviewable.
| Profile | Tools | Prompts | Resources | Purpose |
|---|---|---|---|---|
inspect | 30 | 2 | 0 | Offline inspection and diagnostics |
workflow (default) | 34 | 3 | 3 | Reviewable transactional FCPXML edits |
edit | 75 | 5 | 3 | Direct offline mutation plus workflows |
full | 94 | 5 | 3 | All offline tools and opt-in live FCP, media, and Compressor tools |
The 94 tools include the youtube-mcp.materialized-clip-plan/v1 provenance
adapter, fcpxml_generate_from_clip_plan, in edit and full only. Live FCP
control remains independently disabled unless FCP_MCP_ENABLE_LIVE_CONTROL=1;
choosing full does not grant that authority.
full)The full catalog combines 93 domain tools across 13 functional categories with
fcp_doctor.
| Category | Count | What it does |
|---|---|---|
| inspect | 8 | Parse, list clips/markers/effects/roles, analyze pacing, timeline stats, A/B diff |
| qc | 10 | Flash frames, gaps, duplicates, media links, frame rates, audio levels, safe zones, duration, structural validation, aggregate QC report |
| edit | 12 | Markers, keywords, titles, audio, transitions, trim, split, delete, reorder, speed, role assign, reformat |
| heal | 3 | Fix flash frames, fill gaps, remove silence |
| batch | 4 | Markers, rename, role assign, apply transition across many clips |
| generate | 5 | New project/timeline, rough cuts, montages, and provenance-preserving clip-plan FCPXML |
| templates | 3 | List and save FCPXML templates; fcpxml_apply_template remains unsupported_contract in v0.3.0 |
| io | 5 | Import SRT/EDL, export EDL + DaVinci Resolve XML + Premiere FCP7 XMEML |
| live | 20 | AppleScript-backed library/events/projects, playback, menu/keyboard, share, and discovery |
| puppet | 7 | Parametric character rigs in FCPXML with motion presets |
| media | 10 | ffprobe + ffmpeg info, loudness, silence, beats, scenes, thumbnails, and audio-to-MIDI |
| compressor | 2 | List Compressor settings and dispatch encode jobs |
| workflow | 4 | Prepare, inspect, hash-approve, commit, or cancel durable edit runs |
Most FCP MCPs pick a lane. DareDev256/fcpxml-mcp-server is FCPXML-only. elliotttate/finalcutpro-mcp is AppleScript/JXA-heavy with thin FCPXML. fcp-mcp does both — and adds media analysis (ffprobe) and a parametric puppet system on top. An agent can open a library, inspect the active timeline, patch the XML, re-import, trigger Share, and dispatch a Compressor job — end to end.
Time values are stored as fractions ("720/24s") and only collapsed to
floats at display boundaries. Frame-accurate across 23.976 / 24 / 29.97 /
59.94 / drop-frame — no rounding drift when splitting, trimming, or
concatenating.
All .fcpxml reads go through defusedxml via utils/safe_xml.py —
XXE, entity expansion, and external entities are blocked by default.
The parser enforces configured XML size and depth limits.
User paths are resolved beneath configured roots after symlink resolution. FCPXML writes are serialized to a secure temporary file beside the destination, structurally validated, backed up when replacing an existing destination, atomically committed, and validated again. The built-in validator checks the invariants it implements; it is not a complete Apple schema validator. Import into a disposable Final Cut Pro project is the authoritative compatibility gate for important outputs. On a release workstation with Final Cut Pro installed, preflight a candidate against the DTD matching its declared FCPXML version:
This gate reads the DTD from the installed Final Cut Pro application bundle; the project does not copy or redistribute Apple's schema. A passing DTD check does not replace the disposable-project import because Final Cut Pro also checks media and application-level semantics.
fcpxml_assign_role, fcpxml_batch_assign_roles, and their workflow
operations assign audio roles. For an asset-clip, fcp-mcp writes Apple's
audioRole attribute and continues to read legacy role values for
compatibility.
The default profile exposes four workflow tools:
fcpxml_workflow_prepare, fcpxml_workflow_status,
fcpxml_workflow_commit, and fcpxml_workflow_cancel.
Prepare runs a fixed, bounded edit graph and stores the candidate, semantic
diff, validation evidence, and event chain beneath the private
FCP_MCP_STATE_DIR. It does not create or change the public destination.
Review the returned summary and diff_uri, then pass the exact returned
candidate_sha256 to commit as expected_candidate_sha256. Client approval
is cryptographically bound to that candidate but is recorded as
client_unverified_human; the server cannot independently prove that a human
approved a chat message.
Three read-only templates expose durable evidence:
fcp-workflow://runs/{run_id},
fcp-workflow://runs/{run_id}/events, and
fcp-workflow://runs/{run_id}/diff. Candidate XML is deliberately private
and is not exposed as a resource. Interrupted commits are assessed from
durable evidence and can be explicitly reconciled with:
This is a bounded workflow engine, not a generic graph runtime. It does not use MCP Tasks or run background autonomous agents.
Same timeline out to three targets:
fcpxml_export_resolve — DaVinci Resolve-flavored XML (v1.9)fcpxml_export_fcp7 — Premiere-compatible XMEML (FCP7 format)fcpxml_export_edl — flat EDL for color-grading and archive pipelinespuppet_* tools build animated character rigs entirely in FCPXML —
no third-party motion templates required. Parts, keyframes, and
presets (walk, talk, wave, multi-character compositions) emit XML for
structural validation followed by a disposable-project FCP import gate.
Media links, frame rates, audio levels, safe zones, and target duration
are separate fcpxml_check_* tools. Run the specific checks you need
instead of assuming the aggregate report includes them.
When FCP is running, fcp_* tools wire through AppleScript:
By default, modified FCPXMLs are written next to their input with a
_modified suffix. Override per-call via the output_path parameter,
or set the canonical directory for relative and generated outputs:
FCP_PROJECTS_DIR remains a legacy fallback when
FCP_MCP_OUTPUT_DIR is unset. Relative input paths resolve beneath the
output directory.
Allow additional input roots with the macOS path separator (:):
Absolute and symlink-resolved inputs outside those roots are rejected.
For an input-backed operation, explicit outputs may be beneath the
output directory or the input file's parent. Input and output resolving
to the same file are always rejected. Replacing an existing destination
creates a sibling backup named
<file>.bak.<UTC timestamp>.<transaction UUID>.
Live FCP, Accessibility, and Compressor actions are opt-in:
Leave it unset for offline-only use. Runtime and transaction events use
text by default; set FCP_MCP_LOG_FORMAT=json for JSON lines.
Workflow state defaults to the macOS application-support directory. Override it when isolation is required:
See the full gallery for tool sequences and workflow breakdowns. Sample prompts:
fcp-mcp: command not found — make sure the venv you installed into is on
your PATH, or use the absolute path to the venv's bin/fcp-mcp in your MCP config.
ffmpeg: command not found on media_ calls* — brew install ffmpeg. FFmpeg
is not bundled.
fcp_* tools return "Final Cut Pro is not running" — launch FCP first. Live
tools require an active FCP process on macOS and
FCP_MCP_ENABLE_LIVE_CONTROL=1.
fcp_* tools fail silently on newer FCP versions — FCP's scripting surface is
limited compared to pre-FCPX versions. Menu items and keyboard shortcuts are the
reliable path; some JXA queries are gated behind Accessibility permissions
(System Settings → Privacy & Security → Accessibility → Claude/Terminal).
fcpxml_* tools report structural validation failures — run
fcpxml_validate for the implemented checks. Passing this validator is
not proof of complete Apple/FCP compatibility. Run
python scripts/apple_dtd_gate.py path/to/result.fcpxml on a Mac with
Final Cut Pro installed, then import an important result into a disposable
Final Cut Pro project before relying on it.
path_outside_scope — add the media location to
FCP_MCP_ALLOWED_ROOTS. External volumes are not implicitly trusted.
same_file_forbidden — choose a different output. fcp-mcp never
overwrites its source path, even when the caller supplies it explicitly.
unsupported_contract from fcpxml_apply_template — template
listing and saving remain available, but clip substitution has no stable
schema and remains intentionally unavailable in v0.3.0.
Tests failing on import — activate the venv and reinstall: pip install -e ".[dev]".
See ROADMAP.md for the full plan. Highlights:
qc-check, youtube-chapters, cleanup, rough-cut, beat-syncfcp-mcp was co-developed by Adam Steen and Claude (Anthropic).
MIT — see LICENSE.