# fcp-mcp-server [Health: Active]

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

## Description
MCP server for Final Cut Pro XML. Lets Claude read, edit and generate real timelines: cut detection, markers, roles, transcript-based editing. Published on PyPI as fcp-mcp-server.

## 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, list_keyframes, list_speed_points.
- **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, set_keyframes, delete_keyframes, batch_keyframes, set_animation_curve, set_speed_curve, reset_speed.
- **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; pictures come back inline: a 720p proxy (burn_in), a labelled sheet of every clip (layout: phone), a frame (burn), or a filmstrip+waveform check of the SOURCE MEDIA (cut; filepath: what the edit removed). Confirms a fix. 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.
- **view** — 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.
- **gen** — 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.

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

```json
"mcpServers": {
  "fcp-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 fcp-mcp-server does

fcp-mcp-server gives an MCP client access to Final Cut Pro timelines through FCPXML files. It can read a project, return a structured timeline, and write an edited result that can be imported into Final Cut Pro. It also supports interaction with a running Final Cut Pro installation for pushing a delivered project.

The workflow is designed for batch editing tasks that are tedious to perform manually. Examples include removing silent sections, placing markers from transcript content or beats, assigning roles, building rough cuts, applying keyframes and speed changes, and making transcript-based edits. Cross-NLE export is included among the editing operations.

## How it works

First export a timeline from Final Cut Pro with `File → Export XML…`. Configure the server with a projects directory, then start it as an MCP process from the client. The agent can inspect the imported timeline with `view_timeline`, which returns exact rational-time JSON. MCP Apps hosts can render that result in an inline timeline view with lanes, thumbnails, markers, transcript words, and a playhead; other clients receive the summary and JSON as text. The `preview` operation returns images and an MP4 path.

Writes are recorded in a journal with a SHA-256 value. An `expected_sha256` check can reject an operation if the file changed after the model inspected it, and journaled outputs can be undone. Delivery also requires the cut to have been reviewed. Media generation follows a quote-then-confirm process and applies a per-call spending cap.

## Setup and configuration

Python 3.10 or newer is required, along with Final Cut Pro for Mac versions 10.4 through 12.4. With `uvx`, add the server to Claude Code or Claude Desktop using the `FCP_PROJECTS_DIR` environment variable:

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

For local development, clone the repository, install it with `pip install -e .`, and configure the MCP client to run `python /path/to/fcp-mcp-server/server.py`. Optional extras provide beat detection and local Whisper transcript editing:

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

## Tools and capabilities

The server groups 102 operations into 15 tool families. Supported work includes:

- Inspecting timelines and returning rendered previews.
- Trimming, splitting, and removing media silence.
- Adding individual or batches of markers, including markers derived from transcripts and beats.
- Editing transcripts, creating rough cuts, and exporting to other NLE formats.
- Applying video and audio keyframes, holds, sampled speed ramps, ripple changes, and speed resets.
- Generating media through quote and confirmation steps.
- Assigning roles and importing a result into a running Final Cut Pro instance.
- Reviewing journal history and undoing recorded outputs.

## Limitations and notes

The workflow starts with an FCPXML export rather than a direct Final Cut Pro plugin. Final Cut Pro for Mac is the supported editing application. Inline timeline rendering depends on the MCP client being an MCP Apps host; Claude Code receives text and preview images instead of rendering the UI. Hosts that require MCP Apps extension advertisement need MCP SDK 2.x, while MCP 1.x can still carry the UI metadata and serve the resource.

The server uses sandboxed writes, `defusedxml`, and no private Final Cut Pro APIs. Running-project delivery depends on verification against Final Cut Pro, including polling until the imported project appears.

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