# DareDev256/fcpxml-mcp-server [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/DareDev256/fcpxml-mcp-server  
**GitHub Stars:** 130  
**Views:** 14  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/daredev256-fcpxml-mcp-server

## Description
The first MCP server for Final Cut Pro. 53 tools that parse, edit, and generate FCPXML timelines — health checks, flash frame detection, chapter markers, rough cuts, NLE export. 912 tests, MIT licensed.

## Tools
Capabilities this server exposes over MCP:

- **inspect** — Read a timeline or project without changing it. Use this first to understand what you are working with. Actions: list_projects, analyze_timeline, analyze_pacing, list_clips, list_markers, list_roles, list_keywords, list_effects, list_templates, list_library_clips, list_compound_clips, list_connected_clips, filter_by_role.
- **diagnose** — Find problems in a timeline: gaps, flash frames, duplicates, dead air, and beat structure. Read-only. Run before editing. Actions: validate_timeline, detect_gaps, detect_duplicates, detect_flash_frames, detect_silence_candidates, detect_media_silence, detect_beats, find_short_cuts, find_long_clips, diff_timelines.
- **edit** — Change clips on the timeline: insert, delete, trim, split, reorder, retime, remove silence, and attach audio, B-roll or transitions. Writes a new file. Actions: insert_clip, delete_clips, trim_clip, split_clip, reorder_clips, change_speed, rapid_trim, add_transition, add_audio, add_connected_clip, assign_role, fill_gaps, fix_flash_frames, remove_silence_candidates, remove_media_silence.
- **mark** — Add or import markers and chapters, including from SRT/VTT subtitles, transcripts, and beat analysis. Actions: add_marker, batch_add_markers, import_srt_markers, import_transcript_markers, import_beat_markers, snap_to_beats.
- **generate** — Build new timeline structure from source clips: rough cuts, montages, A/B roll, templates and compound clips. Actions: auto_rough_cut, generate_ab_roll, generate_montage, apply_template, create_compound_clip, flatten_compound_clip, import_edl_json.
- **transcript** — Transcribe source media locally and edit the timeline by what was SAID rather than by timecode. Also removes filler words. Actions: transcribe_media, edit_by_transcript, remove_filler_words, transcript_pack.
- **deliver** — Get the edit out: export to other NLEs, CSV, EDL and stems, reformat, relink media, or push straight into a running Final Cut Pro. Exports and push refuse a cut with no rendered preview of its current state (pass confirm_unreviewed=true to ship anyway). Actions: export_csv, export_edl, export_fcp7_xml, export_resolve_xml, export_role_stems, reformat_timeline, relink_media, push_to_fcp, list_fcp_libraries.
- **preview** — See the edit without opening Final Cut Pro. Render a proxy video of the timeline, a contact sheet of every cut, a single frame, or a filmstrip-plus-waveform check read from the SOURCE MEDIA rather than from the XML. Run preview_check to confirm a fix actually landed. Actions: preview_render, preview_sheet, preview_frame, preview_check, preview_timeline.
- **watch** — Close the round-trip. Watch the Final Cut Pro export folder, detect the XML the moment it lands, and diff it against the last one seen. Pair with deliver.push_to_fcp for a full loop: push in, edit, Cmd-E, watch_pull. Actions: watch_start, watch_status, watch_stop, watch_pull.
- **index** — The analysis cache under ~/.fcp-mcp/index.db. index_status shows what is cached and how old it is; index_build warms it for every source in a timeline (args: filepath, with_transcript); index_clear drops it. Every other tool works with the index off (FCP_MCP_INDEX=off) — this only makes the second question fast. Actions: index_status, index_build, index_clear.
- **scenes** — Shot boundaries. detect_scenes reads every source in a timeline and reports cuts in timeline time (args: filepath, clip_name?, backend auto|content|adaptive|ffmpeg, threshold?, min_scene_len=0.5); scenes_to_markers writes a marker at each cut; scenes_split cuts the clips there. PySceneDetect via the scenes extra, ffmpeg without it — the result names which one answered. Actions: detect_scenes, scenes_to_markers, scenes_split.
- **organize** — Bulk library logging and the ledger. organize_auto proposes keywords per clip from cached captions and the transcript (apply=true writes them). Select clips with clip_name (glob), keyword and/or role, then organize_keywords (keywords, mode add|remove|replace), organize_rate (rating favorite|rejected|clear) or organize_roles (audio_role, video_role); each writes a _organized copy. history lists every recorded operation for the file's folder (limit); undo (n) moves the outputs of the last n writes into the journal's undone/ folder — it never deletes and refuses when a file changed since it was written. Actions: organize_auto, organize_keywords, organize_rate, organize_roles, history, undo.
- **find** — Natural-language shot search. find_shots (filepath, query, limit=10, visual=false, clip_name?) ranks moments by what was said (transcript), what was logged (names, keywords, notes, markers, audio events) and, when a local vision model is installed, what the frames look like — the first line of every result names which tiers answered and why one could not. find_index (captions=true, backend) warms scenes and captions and reports which clips have no transcript (it never transcribes or goes online). find_to_timeline (min_source_separation=1, output_path?) assembles the hits into a _found selects reel and reports its diversity score. Actions: find_index, find_shots, find_to_timeline.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "fcpxml-mcp-server": {
    "command": "uvx",
    "args": ["fcp-mcp-server"],
    "env": {
      "FCP_PROJECTS_DIR": ""
    }
  }
}
```

**Requires environment variables:** `FCP_PROJECTS_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What DareDev256/fcpxml-mcp-server does

DareDev256/fcpxml-mcp-server gives an MCP client structured access to Final Cut Pro timelines. It reads exported FCPXML, represents clips and timing as structured data, and writes new XML files for edited results. The original project file is preserved while changes are written to a separate output.

Its grouped tools cover timeline inspection, quality checks, clip editing, markers, timeline generation, transcription, previews, delivery, indexing, scene detection, library organization, and natural-language shot search. Read-only inspection and diagnosis can be used before any write operation. The server can identify gaps, duplicate clips, flash frames, silence candidates, beat structure, short cuts, long clips, and differences between timelines.

## How it works

Export an XML timeline from Final Cut Pro, point the MCP client at the server, and ask the client to analyze or modify the file. The server parses the XML into Python objects, applies operations, and saves a new FCPXML result that can be imported back into Final Cut Pro. Timeline times remain rational fractions rather than rounded decimal values, supporting frame-accurate operations across different frame rates.

The `preview` group can render a proxy video, contact sheet, frame, or filmstrip with waveform information without opening Final Cut Pro. `preview_check` helps verify that a requested change appears in the result. The `watch` group monitors the Final Cut Pro export folder and compares newly detected XML with the last file seen, supporting a push-edit-export round trip.

## Setup and configuration

The documented quick-start path uses `uvx` and the `FCP_PROJECTS_DIR` environment variable:

```bash
claude mcp add fcpxml -e FCP_PROJECTS_DIR=~/Movies -- uvx fcp-mcp-server
```

Claude Desktop can run the same command through its MCP configuration file. Source installation is also available with `pip install -e .`, followed by pointing the client at `server.py`. After installation, export a timeline from Final Cut Pro using `File → Export XML…`.

Optional extras add media intelligence and local Whisper transcription:

```bash
uvx --from "fcp-mcp-server[intelligence,transcribe]" fcp-mcp-server
```

Scene detection can use PySceneDetect when the scenes extra is installed, or ffmpeg otherwise. The index cache is stored under `~/.fcp-mcp/index.db`; setting `FCP_MCP_INDEX=off` disables it without disabling the other tools.

## Tools and capabilities

- **Inspect and diagnose:** Read project structure, clips, roles, markers, effects, templates, keywords, pacing, gaps, duplicates, flash frames, silence, beats, and timeline differences.
- **Edit timelines:** Insert, delete, trim, split, reorder, retime, remove silence, attach audio or B-roll, add transitions, assign roles, fill gaps, and repair flash frames.
- **Generate and mark:** Build rough cuts, montages, A/B-roll structures, templates, compound clips, and markers from SRT, VTT, transcripts, or beat analysis.
- **Transcribe and search:** Transcribe local media, edit by spoken content, remove filler words, search shots using transcripts and logged metadata, and assemble search results into a selects reel.
- **Preview and analyze media:** Render proxies and contact sheets, inspect frames and source-media waveforms, detect scenes, and turn scene boundaries into markers or cuts.
- **Deliver and organize:** Export CSV, EDL, FCP7 XML, Resolve XML, and role stems; reformat or relink media; push to Final Cut Pro; apply keywords, ratings, and roles; and review or undo recorded organization operations.

## Limitations and notes

The workflow is based on FCPXML exchange rather than a Final Cut Pro plugin. Creative judgments such as color, framing, and motion still require human review. Delivery and push operations require a rendered preview unless `confirm_unreviewed=true` is supplied. Transcript editing and media intelligence use local processing options, while visual shot search requires a locally installed vision model for frame-based results.

_Full upstream README: https://allmcps.com/mcp/daredev256-fcpxml-mcp-server/readme_