io.github.DareDev256/fcpxml-mcp-server

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.

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.

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, set_keyframes, delete_keyframes, batch_keyframes, set_animation_curve, set_speed_curve, reset_speed.

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.

Generative fill, quote-then-confirm. gen_quote(provider, seconds, prompt, model?) prices a job from a dated table (fal: kling-2.5, wan-2.5; gemini: veo-3.1; runway/luma are honest stubs) and returns a quote id. gen_fill_gap(filepath, prompt, gap_index|at), gen_broll(filepath, clip_name, prompt, seconds=5, at?) and gen_extend_clip(filepath, clip_name, seconds=5) REFUSE without quote_id + confirm=true, a matching job, a key in the environment (FAL_KEY / GEMINI_API_KEY) and a price under FCP_MCP_GEN_MAX_USD (default 5). The result is probed with ffprobe for its real fps and length, saved under generated/ next to the project, attached as a connected clip with role `generated` and a marker naming prompt and provider, DTD-validated and journaled. Actions: gen_quote, gen_fill_gap, gen_broll, gen_extend_clip.

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.

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.

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, list_keyframes, list_speed_points.

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.

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.

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.

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.

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.

See the cut inline. view_timeline(filepath, thumbnails=true, words=true) returns the timeline — lanes, clips, markers, gaps, cached transcript words and filmstrip thumbnails — as an exact rational-time JSON payload that hosts with MCP Apps render as an interactive timeline (clip details, range selection, inspect / find-similar / marker / delete buttons that call the other tools). view_clip(filepath, clip_name) is the inspect button. Read-only; edits go through edit and mark. Actions: view_timeline, view_clip.

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.