FCPXML MCP

The bridge between Final Cut Pro and AI. 56 tools that turn timeline XML into structured data Claude can read, edit, and generate.

---

Why This Exists

After directing 350+ music videos (Chief Keef, Migos, Masicka), I noticed the same editing bottlenecks on every project: counting cuts manually, extracting chapter markers one by one, hunting flash frames by scrubbing, building rough cuts clip by clip.

These are batch operations that don't need visual feedback. Export the XML, let Claude handle the tedium, import the result. That's the entire philosophy.

---

See It In Action

You:    "Run a health check on my wedding edit"

Claude: ✓ Analyzed WeddingFinal.fcpxml
        ├─ 247 clips · 42:18 total · 24fps · 1920×1080
        ├─ 3 flash frames detected (clips 44, 112, 198)
        ├─ 2 unintentional gaps at 12:04 and 31:47
        ├─ 14 duplicate source clips
        └─ Health score: 72/100

You:    "Fix the flash frames and gaps, then add chapter markers from
         this transcript"

Claude: ✓ Extended adjacent clips to cover 3 flash frames
        ✓ Filled 2 gaps by extending previous clips
        ✓ Added 18 chapter markers from transcript
        → Saved: WeddingFinal_modified.fcpxml

Import the modified XML back into Final Cut Pro. Every change is non-destructive — your original file is never touched.

---

What Claude Actually Sees

This is the magic trick. When you export XML from Final Cut Pro, your timeline becomes structured data that Claude can reason about:

<asset-clip ref="r2" offset="342/24s" name="Interview_A"
            start="120s" duration="720/24s" format="r1">
    <marker start="48/24s" duration="1/24s" value="Key quote"/>
    <keyword start="0s" duration="720/24s" value="Interview"/>
</asset-clip>

# What Claude works with (after parsing)
Clip(
    name="Interview_A",
    offset=TimeValue(342, 24),   # timeline position: 14.25s
    start=TimeValue(120, 1),     # source in-point: 2:00
    duration=TimeValue(720, 24), # 30 seconds
    markers=[Marker(value="Key quote", start=TimeValue(48, 24))],
    keywords=["Interview"]
)

Every time value stays as a rational fraction — 720/24s, not 30.0 — so trim, split, and speed operations have zero rounding error across any frame rate. Comparisons use cross-multiplication (a/b < c/d → a*d < c*b) to stay in integer-land end to end. Denominators are always normalized to positive values at construction, so sign lives on the numerator and cross-multiplication is always correct. Addition and subtraction share a single _binop() code path that handles same-denominator fast paths and LCM alignment in one place.

---

How It Works

  ┌──────────┐      ┌──────────────────────────────┐      ┌──────────┐
  │ Final Cut│      │  parser.py   → Python objects │      │ Final Cut│
  │   Pro    │─XML─>│  writer.py   → Modify & save  │─XML─>│   Pro    │
  │          │      │  rough_cut.py→ Generate new   │      │          │
  └──────────┘      │  diff.py     → Compare        │      └──────────┘
                    │  export.py   → Resolve / FCP7 │
                    └──────────────────────────────┘
                              ▲
                     Claude Desktop / MCP client

1. Export from FCP — File → Export XML...
2. Ask Claude — analyze, edit, generate, QC, export
3. Import back — File → Import → XML

What This Is NOT

• Not a plugin — it doesn't run inside Final Cut Pro
• Not for creative calls — color, framing, motion still need your eyes

New in v0.9 — Live Mode. The server can now push an FCPXML straight into the running Final Cut Pro with zero clicks, using Apple's official Open Document event — no XML re-import step. See Live Mode below.

---

Live Mode (macOS)

XML mode is offline and portable; Live mode drives a running Final Cut Pro through Apple's sanctioned surfaces — no patched binary, no private APIs, no accessibility scripting. Two tools, both verified end-to-end against FCP 12.2:

Tool	What it does
push_to_fcp	Sends an FCPXML file into FCP with zero clicks (Open Document Apple event). Injects <import-options> (library location, copy/link assets, suppress warnings), launches FCP if needed, and never mutates your original — flat files get an options-injected copy.
list_fcp_libraries	Enumerates FCP's open libraries → events → projects via the read-only AppleScript dictionary.

You:    "Build a rough cut from my Interview clips and push it into Final Cut"

Claude: ✓ Generated RoughCut.fcpxml (8 clips, 0:54)
        ✓ Pushed into Final Cut Pro → library "ProjectX", event 2026-06-11
        → Open Final Cut Pro to keep editing

The asymmetry you must know: Apple makes import scriptable but offers no programmatic export — to pull your current timeline back out for further AI work, you still run File > Export XML yourself. Live mode pushes; round-trips come back through the XML tools.

Notes (all live-verified): pass a library_location ending in .fcpbundle for a true zero-click import (a new path is auto-created); omitting it makes FCP show a modal library picker that blocks until you answer. First use triggers a one-time macOS Automation permission prompt for your terminal/MCP host. The capability audit maps the full surface and the optional SpliceKit/CommandPost bridges planned for v1.0.

---

Quick Start

1. Clone & Install

git clone https://github.com/DareDev256/fcp-mcp-server.git
cd fcp-mcp-server
pip install -e .

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

Using uv (recommended):

{
  "mcpServers": {
    "fcpxml": {
      "command": "uv",
      "args": ["--directory", "/path/to/fcp-mcp-server", "run", "server.py"],
      "env": { "FCP_PROJECTS_DIR": "/Users/you/Movies" }
    }
  }
}

Using pip:

{
  "mcpServers": {
    "fcpxml": {
      "command": "python",
      "args": ["/path/to/fcp-mcp-server/server.py"],
      "env": { "FCP_PROJECTS_DIR": "/Users/you/Movies" }
    }
  }
}

3. Use It

Export XML from Final Cut Pro, open Claude Desktop, and ask it to work with your timeline.

---

When To Use This

Good For	Not Ideal For
Batch marker insertion (100 chapters from a transcript)	Creative editing decisions (no visual feedback)
QC before delivery (flash frames, gaps, duplicates)	Real-time adjustments (export/import cycle)
Data extraction (EDL, CSV, chapter markers)	Fine-tuning cuts (faster directly in FCP)
Template generation (rough cuts from tagged clips)	Anything visual (color, framing, motion)
Automated assembly (montages from keywords + pacing)
Timeline health checks (validation, stats, scoring)

---

Prompt Cookbook

Copy-paste these into Claude Desktop. Each one maps to a real tool chain under the hood.

Analysis

"Give me a full breakdown of ProjectX.fcpxml — clips, duration, frame rate, markers, everything"
"Show me pacing analysis for my timeline — where are the slow sections?"
"Export an EDL and CSV of all clips with timecodes"

QC & Fixes

"Run a health check on my timeline and fix anything under 2 frames"
"Find all gaps and flash frames, then auto-fix them"
"Are there any duplicate source clips I can consolidate?"

Markers & Chapters

"Add chapter markers from this transcript: [paste transcript]"
"Import markers from my-subtitles.srt onto the timeline"
"List all markers and export them as YouTube chapter timestamps"

Generation

"Build a 60-second rough cut from clips tagged 'Interview' — medium pacing"
"Generate a montage from all B-roll clips with accelerating pacing"
"Create an A/B roll: Interview_A as primary, B-roll cuts every 8 seconds"

Cross-NLE & Reformat

"Export this timeline for DaVinci Resolve"
"Convert to FCP7 XML so I can open it in Premiere"
"Reformat my 16:9 timeline to 9:16 for Instagram Reels"

Under the Hood

When you say "Run a health check on my wedding edit", Claude chains these tools:

analyze_timeline  →  stats, frame rate, resolution
detect_flash_frames  →  clips under threshold duration
detect_gaps  →  unintentional silence/black
detect_duplicates  →  repeated source media
validate_timeline  →  structural health score (0-100)

Each tool returns structured text that Claude synthesizes into the summary you see. No magic — just batch XML queries that would take 20 minutes by hand.

---

Pre-Built Prompts

Select these from Claude's prompt menu (⌘/) — they chain multiple tools automatically.

Prompt	What It Does
qc-check	Full quality control — flash frames, gaps, duplicates, health score
youtube-chapters	Extract chapter markers formatted for YouTube descriptions
rough-cut	Guided rough cut — shows clips, suggests structure, generates
timeline-summary	Quick overview — stats, pacing, keywords, markers, assessment
cleanup	Find and auto-fix flash frames and gaps

---

All 56 Tools

Category	Tools	What It Does
Analysis	11	Stats, clips, markers, keywords, EDL/CSV, pacing
Multi-Track	3	Connected clips, compound clips, secondary lanes
Roles	4	List, assign, filter, export stems
QC & Validation	4	Flash frames, duplicates, gaps, health score
Editing	9	Markers, trim, reorder, transitions, speed, split
Batch Fixes	3	Auto-fix flash frames, rapid trim, fill gaps
Comparison	1	Diff two timelines — added/removed/moved/trimmed
Reformat	1	Aspect ratio conversion (9:16, 1:1, 4:5, custom)
Silence	2	Detect and remove silence candidates
NLE Export	2	DaVinci Resolve v1.9, FCP7 XMEML v5
Generation	3	Rough cuts, montages, A/B roll
Beat Sync	2	Import beat markers, snap cuts to beats
Import	2	SRT/VTT subtitles, YouTube chapters → markers
Audio	1	Add audio clips, music beds at any lane
Compound	2	Create/flatten compound clips
Templates	2	Pre-built timeline structures (intro/outro, lower thirds, music video)
Effects	1	List FCP transition effects with UUIDs
Media	1	Bulk relink moved/renamed media (rewrite media-rep src paths)
Live (macOS)	2	Push FCPXML into the running FCP (zero-click Apple-event import); list open libraries
	56

Full tool reference (click to expand)

Analysis — 11 tools

list_projects · analyze_timeline · list_clips · list_library_clips · list_markers · find_short_cuts · find_long_clips · list_keywords · export_edl · export_csv · analyze_pacing

Multi-Track — 3 tools

list_connected_clips · add_connected_clip · list_compound_clips

Roles — 4 tools

list_roles · assign_role · filter_by_role · export_role_stems

QC & Validation — 4 tools

detect_flash_frames · detect_duplicates · detect_gaps · validate_timeline

Editing — 9 tools

add_marker · batch_add_markers · insert_clip · trim_clip · reorder_clips · add_transition · change_speed · delete_clips · split_clip

Batch Fixes — 3 tools

fix_flash_frames · rapid_trim · fill_gaps

Comparison · Reformat · Silence

diff_timelines · reformat_timeline · detect_silence_candidates · remove_silence_candidates

NLE Export — 2 tools

export_resolve_xml (DaVinci Resolve FCPXML v1.9) · export_fcp7_xml (Premiere Pro / Resolve / Avid XMEML v5)

Generation — 3 tools

auto_rough_cut · generate_montage · generate_ab_roll

Beat Sync — 2 tools

import_beat_markers · snap_to_beats

Import — 2 tools

import_srt_markers · import_transcript_markers (supports SMPTE HH:MM:SS:FF with frame-accurate placement)

v0.6.0 — Audio, Compound, Templates, Effects — 6 tools

list_effects · add_audio · create_compound_clip · flatten_compound_clip · list_templates · apply_template

v0.8.0 — Media — 1 tool

relink_media (bulk-rewrite asset/media-rep src paths with dry_run preview — relink a moved drive without opening FCP)

v0.9.0 — Live Mode (macOS + Final Cut Pro) — 2 tools

push_to_fcp (zero-click FCPXML import into the running FCP via Apple event) · list_fcp_libraries (enumerate open libraries/events/projects)

---

Environment Variables

Variable	Required	Default	Description
FCP_PROJECTS_DIR	No	~/Movies	Root directory for FCPXML file discovery via list_projects
FCPXML_DTD_DIR	No	FCP app bundle	Directory of Apple FCPXMLv*_*.dtd files for DTD validation (auto-detected from the installed Final Cut Pro)

---

Compatibility

Component	Supported Versions