Skip to content
Back to search

fcpxml-mcp

AI tools for Final Cut Pro. Drive Final Cut Pro from a conversation: read a timeline, run quality control, batch-edit, build rough cuts, manage markers, transcribe, and export to other NLEs. 15 grouped tools covering 102 operations over .fcpxml and .fcpxmld, with an operation journal and undo.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/daredev256--fcp-mcp-server/badge.svg)](/listings/daredev256--fcp-mcp-server)

HTML

<a href="/listings/daredev256--fcp-mcp-server"><img src="/api/listings/daredev256--fcp-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code (fastest)

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

Or project-scoped — commit a `.mcp.json` so your whole team gets it:

{
  "mcpServers": {
    "fcpxml": {
      "command": "uvx",
      "args": ["fcp-mcp-server"],
      "env": { "FCP_PROJECTS_DIR": "/Users/you/Movies" }
    }
  }
}

With media intelligence (beat detection) and transcript editing (local Whisper):

claude mcp add fcpxml -e FCP_PROJECTS_DIR=~/Movies -- uvx --from "fcp-mcp-server[intelligence,transcribe]" fcp-mcp-server

Claude Desktop

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

{
  "mcpServers": {
    "fcpxml": {
      "command": "uvx",
      "args": ["fcp-mcp-server"],
      "env": { "FCP_PROJECTS_DIR": "/Users/you/Movies" }
    }
  }
}

Where the timeline draws

`view` returns a timeline an MCP Apps host draws inline (`ui://fcp/timeline`) from the result's structured payload. Every other client gets the text: a summary line and the clips in record order (since 0.34 the JSON, thumbnails and all, rides as `structuredContent` and stays out of the text: 609 characters for a five-clip cut, where 0.33 sent 36,701). `preview` returns images and an MP4 path everywhere. Checked 2026-11-12; a host listed by its vendor but not yet captured here says so.

| Host | What you get | Source | |---|---|---| | Claude Desktop | the timeline, inline | listed by the [MCP Apps overview](https://modelcontextprotocol.io/extensions/apps/overview); **not verified in Claude Desktop** for this release (the capture steps are in [`scripts/capture-claude-desktop.md`](scripts/capture-claude-desktop.md)) | | Claude on the web (claude.ai) | the timeline, inline | listed by the MCP Apps overview; not captured here | | VS Code GitHub Copilot, Microsoft 365 Copilot, Goose, Postman, MCPJam, Archestra.AI | the timeline, inline | listed by the MCP Apps overview; not captured here | | `ext-apps` basic host (the reference host) | the timeline, inline, with Inspect and Find calling back into the server | run here on 2026-11-12 against 0.30.0 | | Claude Code | text: the summary and the clip list; `preview` images | Claude's [MCP Apps quickstart](https://claude.com/docs/connectors/building/mcp-apps/quickstart): "Claude Code calls the tool as text and doesn't render the UI" | | ChatGPT | unconfirmed | not named on the MCP Apps overview | | any other MCP client | text | |

On `mcp` 1.x the tool carries `_meta.ui` and the resource is served, but the SDK cannot advertise the extension in the handshake; a host that insists on it needs `mcp` 2.x.

From source (contributors)

git clone https://github.com/DareDev256/fcp-mcp-server.git
cd fcp-mcp-server
pip install -e .
# then point your MCP client at: python /path/to/fcp-mcp-server/server.py

Use It

Export XML from Final Cut Pro (`File → Export XML…`), open your MCP client, and ask it to work with your timeline.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 21 lines
  1. {
  2. "name": "fcpxml-mcp",
  3. "displayName": "fcp-mcp-server",
  4. "version": "0.35.0",
  5. "description": "AI tools for Final Cut Pro. Drive Final Cut Pro from a conversation: read a timeline, run quality control, batch-edit, build rough cuts, manage markers, transcribe, and export to other NLEs. 15 grouped tools covering 102 operations over .fcpxml and .fcpxmld, with an operation journal and undo.",
  6. "author": {
  7. "name": "James Olusoga",
  8. "url": "https://github.com/DareDev256"
  9. },
  10. "license": "MIT",
  11. "homepage": "https://github.com/DareDev256/fcp-mcp-server",
  12. "repository": "https://github.com/DareDev256/fcp-mcp-server",
  13. "keywords": [
  14. "final-cut-pro",
  15. "fcpxml",
  16. "video-editing",
  17. "post-production",
  18. "nle",
  19. "macos"
  20. ]
  21. }
README.md · README · 1,312 lines
  1. <img src="docs/assets/logo-small-400.png" width="72" height="72" alt="">
  2. # AI tools for Final Cut Pro: fcp-mcp-server
  3. **Edit Final Cut Pro by talking to Claude, and watch the cut change.**
  4. Reads and writes FCPXML, no&nbsp;plugin,&nbsp;no&nbsp;patch
  5. [![PyPI](https://img.shields.io/pypi/v/fcp-mcp-server?label=PyPI&color=33EBFF&labelColor=000000)](https://pypi.org/project/fcp-mcp-server/)
  6. [![tests](https://img.shields.io/github/actions/workflow/status/DareDev256/fcp-mcp-server/test.yml?branch=main&label=tests&color=33EBFF&labelColor=000000)](https://github.com/DareDev256/fcp-mcp-server/actions/workflows/test.yml)
  7. [![License: MIT](https://img.shields.io/static/v1?label=license&message=MIT&color=33EBFF&labelColor=000000)](LICENSE)
  8. Python 3.10+ · Final Cut Pro for Mac 10.4 to 12.4 ([compatibility](#compatibility))
  9. ```bash
  10. claude mcp add fcpxml -e FCP_PROJECTS_DIR=~/Movies -- uvx fcp-mcp-server
  11. ```
  12. Then `File → Export XML…` in Final Cut Pro, and ask Claude to work on the file.
  13. [![A staged close-up of the real ui://fcp/timeline view, drawn large on black, with a caption naming each of Claude's tool calls and its result: the finished cut rewinds and empties, view_timeline draws the imported cut in, then the camera pushes in as the long squat set splits and its pieces slide together (the rests cut), as a marker lands on each lift, and as a B-roll clip marked MOCK is laid in on lane 1 over the long set](docs/assets/hero-watch-claude-cut.gif)](docs/assets/hero-watch-claude-cut.mp4)
  14. Staged close-up of the real app's results · [unedited recording →](docs/assets/hero-unedited-recording.mp4)
  15. **You:** Cut the rest between sets, mark every lift, and put B-roll over the
  16. long set.
  17. **Claude**, on four clips already imported with `generate · import_edl_json`:
  18. <!-- hero-calls: the calls demo/hero/build.py records, in its order -->
  19. 1. `view · view_timeline` draws the timeline inline (`ui://fcp/timeline`)
  20. 2. `edit · remove_media_silence` cuts the rests out of the long squat set
  21. 3. `mark · batch_add_markers` puts a marker on each lift
  22. 4. `gen · gen_quote` prices the B-roll under the per-call cap; nothing runs
  23. until `confirm=true`
  24. 5. `gen · gen_broll` lays the clip on lane 1 over the long set
  25. 6. `organize · history` lists every journaled output, each one undoable
  26. <!-- /hero-calls -->
  27. *What is real: the timeline is the `ui://fcp/timeline` app as the server
  28. serves it, drawing the real `view_timeline` results of the real calls above,
  29. and every change is the app's own animation from one result to the next. What
  30. is composed: the stage (only the view's ruler and lanes, drawn large on
  31. black), the captions, the timing, the empty beat before the first call (the
  32. app is handed the imported cut with its clips taken out, so they leave) and
  33. the camera's push onto each edit. The
  34. footage is the author's own gym session (its audio is a test tone, so the
  35. rests are real silence), and the B-roll provider is mocked: the clip is named
  36. "B-roll (mocked)" and carries a MOCK badge. The
  37. [unedited recording](docs/assets/hero-unedited-recording.mp4) is the same
  38. run (the same results, notes and thumbnails, checked by a test) with the app
  39. inside a chat client. [MP4](docs/assets/hero-watch-claude-cut.mp4),
  40. [poster](docs/assets/hero-still.png), recorded with
  41. [`demo/hero/build.py`](demo/hero/build.py).*
  42. **See it.** `view` returns the timeline as exact rational-time JSON, and a
  43. host with MCP Apps draws it inline, like Final Cut's timeline: an overview of
  44. the whole cut, filmstrips with their waveforms, Final Cut's role colours, a glyph
  45. per marker kind, a playhead that snaps to cuts, buttons that call the other
  46. tools.
  47. **Cut it.** 15 grouped tools, 102 operations: trims, splits, silence removal,
  48. markers from transcripts and beats, rough cuts, keyframes and speed ramps,
  49. transcript edits, cross-NLE export, and a push into a running Final Cut Pro.
  50. **Trust it.** Every write is journaled with its sha256 and can be undone.
  51. `deliver` refuses an unreviewed cut, `expected_sha256` refuses a file that
  52. changed under the model, and generation is quote-then-confirm under a
  53. per-call cap. 182 adversarial-input security tests, `defusedxml` everywhere,
  54. sandboxed writes, no private APIs, and a [disclosure channel](SECURITY.md).
  55. ---
  56. ## Proof
  57. ![fcp-mcp-server demo: Final Cut Pro on the left, a terminal on the right. A timeline is read back, a marker is placed on every cut, and roles are assigned across ten clips, with Final Cut open the whole time](docs/assets/demo-live-fcp.gif)
  58. *Real v0.25.0 output against a running copy of Final Cut Pro. A ten clip
  59. timeline is read back off the document, a marker is placed on every cut, and
  60. dialogue, music and effects roles are assigned across the clips. Final Cut is
  61. open on the left the whole time and is never touched by hand. Screen recorded
  62. from [`demo/session.sh`](demo/session.sh), which calls the same handlers an MCP
  63. client calls; each import is verified by polling Final Cut until the project
  64. appears, so a delivered Apple event is never reported as a landed import.
  65. The earlier terminal only demo is still at `docs/assets/demo.gif`.
  66. Re-record it with `vhs demo/demo.tape`; the media is synthesised by ffmpeg at
  67. run time, so there is no fixture to keep.*
  68. ## Keyframes and speed curves
  69. Contributed by [@travisoa](https://github.com/travisoa) in
  70. [#26](https://github.com/DareDev256/fcp-mcp-server/pull/26): the `inspect`
  71. and `edit` groups include five video/audio animation actions and three speed
  72. curve actions, imported into Final Cut Pro 12.4 without warnings. See
  73. [keyframe usage](docs/keyframes.md) for installation and animation, and
  74. [speed curves](docs/retiming.md) for holds, sampled ramps, ripple and reset.
  75. ## Quick Start
  76. ### Claude Code (fastest)
  77. ```bash
  78. claude mcp add fcpxml -e FCP_PROJECTS_DIR=~/Movies -- uvx fcp-mcp-server
  79. ```
  80. Or project-scoped — commit a `.mcp.json` so your whole team gets it:
  81. ```json
  82. {
  83. "mcpServers": {
  84. "fcpxml": {
  85. "command": "uvx",
  86. "args": ["fcp-mcp-server"],
  87. "env": { "FCP_PROJECTS_DIR": "/Users/you/Movies" }
  88. }
  89. }
  90. }
  91. ```
  92. With media intelligence (beat detection) and transcript editing (local Whisper):
  93. ```bash
  94. claude mcp add fcpxml -e FCP_PROJECTS_DIR=~/Movies -- uvx --from "fcp-mcp-server[intelligence,transcribe]" fcp-mcp-server
  95. ```
  96. ### Claude Desktop
  97. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
  98. ```json
  99. {
  100. "mcpServers": {
  101. "fcpxml": {
  102. "command": "uvx",
  103. "args": ["fcp-mcp-server"],
  104. "env": { "FCP_PROJECTS_DIR": "/Users/you/Movies" }
  105. }
  106. }
  107. }
  108. ```
  109. ### Where the timeline draws
  110. `view` returns a timeline an MCP Apps host draws inline (`ui://fcp/timeline`)
  111. from the result's structured payload. Every other client gets the text: a
  112. summary line and the clips in record order (since 0.34 the JSON, thumbnails
  113. and all, rides as `structuredContent` and stays out of the text: 609
  114. characters for a five-clip cut, where 0.33 sent 36,701). `preview` returns
  115. images and an MP4 path everywhere. Checked 2026-11-12; a host listed by its
  116. vendor but not yet captured here says so.
  117. | Host | What you get | Source |
  118. |---|---|---|
  119. | Claude Desktop | the timeline, inline | listed by the [MCP Apps overview](https://modelcontextprotocol.io/extensions/apps/overview); **not verified in Claude Desktop** for this release (the capture steps are in [`scripts/capture-claude-desktop.md`](scripts/capture-claude-desktop.md)) |
  120. | Claude on the web (claude.ai) | the timeline, inline | listed by the MCP Apps overview; not captured here |
  121. | VS Code GitHub Copilot, Microsoft 365 Copilot, Goose, Postman, MCPJam, Archestra.AI | the timeline, inline | listed by the MCP Apps overview; not captured here |
  122. | `ext-apps` basic host (the reference host) | the timeline, inline, with Inspect and Find calling back into the server | run here on 2026-11-12 against 0.30.0 |
  123. | Claude Code | text: the summary and the clip list; `preview` images | Claude's [MCP Apps quickstart](https://claude.com/docs/connectors/building/mcp-apps/quickstart): "Claude Code calls the tool as text and doesn't render the UI" |
  124. | ChatGPT | unconfirmed | not named on the MCP Apps overview |
  125. | any other MCP client | text | |
  126. On `mcp` 1.x the tool carries `_meta.ui` and the resource is served, but the
  127. SDK cannot advertise the extension in the handshake; a host that insists on
  128. it needs `mcp` 2.x.
  129. ### From source (contributors)
  130. ```bash
  131. git clone https://github.com/DareDev256/fcp-mcp-server.git
  132. cd fcp-mcp-server
  133. pip install -e .
  134. # then point your MCP client at: python /path/to/fcp-mcp-server/server.py
  135. ```
  136. ### Use It
  137. Export XML from Final Cut Pro (`File → Export XML…`), open your MCP client, and ask it to work with your timeline.
  138. ---
  139. ## Why This Exists
  140. After a decade directing 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.
  141. 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.
  142. ---
  143. ## See It In Action
  144. ```
  145. You: "Run a health check on my wedding edit"
  146. Claude: ✓ Analyzed WeddingFinal.fcpxml
  147. ├─ 247 clips · 42:18 total · 24fps · 1920×1080
  148. ├─ 3 flash frames detected (clips 44, 112, 198)
  149. ├─ 2 unintentional gaps at 12:04 and 31:47
  150. ├─ 14 duplicate source clips
  151. └─ Health score: 72/100
  152. You: "Fix the flash frames and gaps, then add chapter markers from
  153. this transcript"
  154. Claude: ✓ Extended adjacent clips to cover 3 flash frames
  155. ✓ Filled 2 gaps by extending previous clips
  156. ✓ Added 18 chapter markers from transcript
  157. → Saved: WeddingFinal_modified.fcpxml
  158. ```
  159. Import the modified XML back into Final Cut Pro. Every change is non-destructive — your original file is never touched.
  160. ---
  161. ## What Claude Actually Sees
  162. This is the magic trick. When you export XML from Final Cut Pro, your timeline becomes structured data that Claude can reason about:
  163. ```xml
  164. <!-- What FCP exports -->
  165. <asset-clip ref="r2" offset="342/24s" name="Interview_A"
  166. start="120s" duration="720/24s" format="r1">
  167. <marker start="48/24s" duration="1/24s" value="Key quote"/>
  168. <keyword start="0s" duration="720/24s" value="Interview"/>
  169. </asset-clip>
  170. ```
  171. ```python
  172. # What Claude works with (after parsing)
  173. Clip(
  174. name="Interview_A",
  175. offset=TimeValue(342, 24), # timeline position: 14.25s
  176. start=TimeValue(120, 1), # source in-point: 2:00
  177. duration=TimeValue(720, 24), # 30 seconds
  178. markers=[Marker(value="Key quote", start=TimeValue(48, 24))],
  179. keywords=["Interview"]
  180. )
  181. ```
  182. 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, including the NTSC-fractional ones. A broadcast rate is carried as the exact rational it is (23.976 is `24000/1001`, not a decimal), never as a truncated integer. 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.
  183. ---
  184. ## How It Works
  185. ```
  186. ┌──────────┐ ┌──────────────────────────────┐ ┌──────────┐
  187. │ Final Cut│ │ parser.py → Python objects │ │ Final Cut│
  188. │ Pro │─XML─>│ writer.py → Modify & save │─XML─>│ Pro │
  189. │ │ │ rough_cut.py→ Generate new │ │ │
  190. └──────────┘ │ diff.py → Compare │ └──────────┘
  191. │ export.py → Resolve / FCP7 │
  192. └──────────────────────────────┘
  193. ▲
  194. Claude Desktop / MCP client
  195. ```
  196. 1. **Export from FCP** — `File → Export XML...`
  197. 2. **Ask Claude** — analyze, edit, generate, QC, export
  198. 3. **Import back** — `File → Import → XML`
  199. ### What This Is NOT
  200. - **Not a plugin** — it doesn't run inside Final Cut Pro
  201. - **Not for creative calls** — color, framing, motion still need your eyes
  202. > **New in v0.9 — Live Mode.** The server can now *push* an FCPXML straight
  203. > into the running Final Cut Pro with zero clicks, using Apple's official Open
  204. > Document event — no XML re-import step. See [Live Mode](#live-mode-macos) below.
  205. ---
  206. ## Live Mode (macOS)
  207. XML mode is offline and portable; **Live mode** drives a running Final Cut Pro
  208. through Apple's sanctioned surfaces — no patched binary, no private APIs, no
  209. accessibility scripting. Two tools, both verified end-to-end against FCP 12.2:
  210. | Tool | What it does |
  211. |------|--------------|
  212. | **`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. |
  213. | **`list_fcp_libraries`** | Enumerates FCP's open libraries → events → projects via the read-only AppleScript dictionary. |
  214. ```
  215. You: "Build a rough cut from my Interview clips and push it into Final Cut"
  216. Claude: ✓ Generated RoughCut.fcpxml (8 clips, 0:54)
  217. ✓ Pushed into Final Cut Pro → library "ProjectX", event 2026-06-11
  218. → Open Final Cut Pro to keep editing
  219. ```
  220. **The asymmetry you must know:** Apple makes *import* scriptable but offers **no
  221. programmatic export** — to pull your current timeline back out for further AI
  222. work, you still run `File > Export XML` yourself. Live mode pushes; round-trips
  223. come back through the XML tools.
  224. Notes (all live-verified): pass a `library_location` ending in `.fcpbundle` for
  225. a true zero-click import (a new path is auto-created); omitting it makes FCP
  226. show a modal library picker that blocks until you answer. First use triggers a
  227. one-time macOS Automation permission prompt for your terminal/MCP host. Since
  228. v0.35.0 that prompt no longer blocks a push: if Final Cut does not answer
  229. Apple Events within 10 seconds, the reply quotes the waiting prompt and the
  230. push goes through Launch Services' `open` instead (no grant needed, no
  231. picker), then proves the import from the library on disk. Each media file
  232. keeps one asset uid, so revised versions of a cut can be pushed into the same
  233. library one after another (Final Cut refuses a file it already holds under a
  234. different uid). The
  235. [capability audit](docs/CAPABILITY-AUDIT-2026-06.md) maps the full surface and
  236. the optional SpliceKit/CommandPost bridges planned for v1.0.
  237. ---
  238. ## The Round Trip
  239. Final Cut Pro has a fully scriptable **import** and **no programmatic export** —
  240. verified unchanged across FCP 11.0 → 12.2. So the loop closes on exactly one
  241. keystroke, and everything either side of it is automated:
  242. ```
  243. watch_start ← once per session (or set FCP_WATCH_DIR)
  244. ↓
  245. edit / generate / mark ← the change
  246. ↓
  247. preview_check ← SEE it. Reads the media, not the XML
  248. ↓
  249. deliver.push_to_fcp ← zero-click import (or FCP_MCP_AUTOPUSH=1)
  250. ↓
  251. Cmd-E in Final Cut Pro ← the one manual step Apple leaves you
  252. ↓
  253. watch_pull ← detected and diffed against the last export
  254. ```
  255. **`preview_check` is the part that matters.** The `preview://` resource and
  256. `preview_timeline` both draw from the XML — they show what was *written*, so a
  257. fixed flash frame and a broken one read identically through them. `preview_check`
  258. samples the source media into a filmstrip over an audio waveform. It is the
  259. difference between a tool reporting success and you knowing the cut is right.
  260. If you have SpliceKit or CommandPost installed, `watch_start` says so. This
  261. server **does not call either one** — their RPC signatures have not been verified
  262. against a live install, and it never patches or injects anything. That is why it
  263. runs on a managed Mac and survives an FCP update.
  264. ---
  265. ## When To Use This
  266. | Good For | Not Ideal For |
  267. |----------|---------------|
  268. | Batch marker insertion (100 chapters from a transcript) | Fine-tuning cuts (faster directly in FCP) |
  269. | QC before delivery (flash frames, gaps, duplicates) | Colour, framing and motion (nothing here grades) |
  270. | Data extraction (EDL, CSV, chapter markers) | Sound mixing beyond stems and role splits |
  271. | Template generation (rough cuts from tagged clips) | Anything needing a scrub through the actual cut |
  272. | Automated assembly (montages from keywords + pacing) | |
  273. | Timeline health checks (validation, stats, scoring) | |
  274. | Logging and search before the edit (scenes, transcript, shot search) | |
  275. **Client notes or Frame.io comments to place?** [frameio-to-final-cut-pro](https://github.com/DareDev256/frameio-to-final-cut-pro) (Cut Review, built on this server's parser) writes them into the cut as Final Cut to-do markers on the right clips, then shows which notes the recut touched.
  276. **Generating b-roll, inserts or title plates with AI?** The [Ultimate Image & Video Prompt Generator](https://prompts.tdotssolutionsz.com) builds the prompt for Veo, Kling, Seedance or Nano Banana, and its [face blur](https://prompts.tdotssolutionsz.com/blur-face-in-photo) cleans a still on your device before it goes in the cut.
  277. ---
  278. ## How It Compares
  279. Three projects have connected AI agents to Final Cut Pro. They make different trade-offs:
  280. | | **fcp-mcp-server** (this) | [SpliceKit](https://github.com/elliotttate/SpliceKit) | [CommandPost](https://commandpost.fcp.cafe/) |
  281. |---|---|---|---|
  282. | Approach | Parses/writes FCPXML + official Apple events only | Patches FCP's binary to expose internal APIs | Accessibility scripting + Lua |
  283. | Raw live control | Push-to-FCP, library inspection | Deepest (full internal API) | Deep (UI-level) |
  284. | Survives FCP updates | **Yes — no patching** | Re-patch per FCP version | Mostly |
  285. | Works on managed/corporate Macs | **Yes** | No (requires binary patching) | Varies (Accessibility perms) |
  286. | Works without FCP installed | **Yes** (pure XML mode) | No | No |
  287. | MCP server | **Yes, active** (this repo) | Yes (last release v3.3.9, 2026-08-29) | Planned, [PR unmerged](https://github.com/CommandPost/CommandPost/pull/3514) |
  288. | Requires | Python 3.10+ | Patched FCP binary | CommandPost app |
  289. The editing apps' own makers, checked 2026-11-12: DaVinci Resolve 21.1 ships
  290. a native MCP server ([Blackmagic's 21.1 notes](https://www.blackmagicdesign.com/support/content/readme/baf7c071c0524fbf8ccc961925c9f443),
  291. updated 2026-09-08; reported as Studio only by secondary sources). Adobe says
  292. MCP integrations come to Creative Cloud customers in early 2027
  293. ([Adobe, 2026-11-10](https://blog.adobe.com/en/publish/2026/11/10/explore-new-ways-create-across-creative-cloud-adobe-firefly-while-advancing-craft-precision-choice-control)).
  294. Apple ships no MCP and no new automation surface for Final Cut Pro through
  295. 12.4 ([release notes](https://support.apple.com/en-us/102825)), so FCPXML and
  296. Apple events remain the sanctioned way in.
  297. SpliceKit's runtime depth is genuinely impressive — if you're on your own Mac and comfortable patching FCP, it can do things XML never will. This project stays on the no-patch side so it runs anywhere, survives every FCP update, and can be trusted with client libraries. Full ecosystem analysis: [capability audit](docs/CAPABILITY-AUDIT-2026-06.md).
  298. ---
  299. ## Prompt Cookbook
  300. Copy-paste these into Claude Desktop. Each one maps to a real tool chain under the hood.
  301. **Analysis**
  302. ```
  303. "Give me a full breakdown of ProjectX.fcpxml — clips, duration, frame rate, markers, everything"
  304. "Show me pacing analysis for my timeline — where are the slow sections?"
  305. "Export an EDL and CSV of all clips with timecodes"
  306. ```
  307. **QC & Fixes**
  308. ```
  309. "Run a health check on my timeline and fix anything under 2 frames"
  310. "Find all gaps and flash frames, then auto-fix them"
  311. "Are there any duplicate source clips I can consolidate?"
  312. ```
  313. **Markers & Chapters**
  314. ```
  315. "Add chapter markers from this transcript: [paste transcript]"
  316. "Import markers from my-subtitles.srt onto the timeline"
  317. "List all markers and export them as YouTube chapter timestamps"
  318. ```
  319. **Generation**
  320. ```
  321. "Build a 60-second rough cut from clips tagged 'Interview' — medium pacing"
  322. "Generate a montage from all B-roll clips with accelerating pacing"
  323. "Create an A/B roll: Interview_A as primary, B-roll cuts every 8 seconds"
  324. ```
  325. **Cross-NLE & Reformat**
  326. ```
  327. "Export this timeline for DaVinci Resolve"
  328. "Convert to FCP7 XML so I can open it in Premiere"
  329. "Reformat my 16:9 timeline to 9:16 for Instagram Reels"
  330. ```
  331. ### Under the Hood
  332. When you say *"Run a health check on my wedding edit"*, Claude chains these tools:
  333. ```
  334. analyze_timeline → stats, frame rate, resolution
  335. detect_flash_frames → clips under threshold duration
  336. detect_gaps → unintentional silence/black
  337. detect_duplicates → repeated source media
  338. validate_timeline → structural health score (0-100)
  339. ```
  340. 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.
  341. ### Music videos and connected clips
  342. A music video is usually built by laying an audio bed and hanging every visual
  343. off it as a connected clip, so the spine holds one `<gap>` and the entire edit
  344. lives on lanes. `snap_to_beats` and `detect_flash_frames` work on that shape:
  345. snapping runs lane by lane, does not ripple the clips after the one it moves,
  346. skips (and names) any move that would collide with a neighbour in the same
  347. lane, and leaves the audio bed alone unless you pass `include_audio_lanes`.
  348. It reports cuts considered, moved, already on a beat, out of reach, and
  349. skipped — so "nothing moved" is something you are told rather than something
  350. you discover in Final Cut.
  351. `reorder_clips`, `rapid_trim`, `fix_flash_frames` and `fill_gaps` are still
  352. primary-storyline only.
  353. ---
  354. ## Pre-Built Prompts
  355. Select these from Claude's prompt menu (⌘/) — they chain multiple tools automatically.
  356. | Prompt | What It Does | Grouped calls it drives |
  357. |--------|-------------|-------------------------|
  358. | **qc-check** | Full quality control — flash frames, gaps, duplicates, health score | `diagnose` → `validate_timeline`, `detect_flash_frames`, `detect_gaps`, `detect_duplicates`; then `edit` → `fix_flash_frames`, `fill_gaps` |
  359. | **youtube-chapters** | Extract chapter markers formatted for YouTube descriptions | `inspect` → `list_markers`, `analyze_pacing` |
  360. | **rough-cut** | Guided rough cut — shows clips, suggests structure, generates | `inspect` → `list_library_clips`, `list_keywords`; then `generate` → `auto_rough_cut` |
  361. | **timeline-summary** | Quick overview — stats, pacing, keywords, markers, assessment | `inspect` → `analyze_timeline`, `analyze_pacing`, `list_keywords`, `list_markers` |
  362. | **cleanup** | Find and auto-fix flash frames and gaps | `diagnose` → `validate_timeline`; then `edit` → `fix_flash_frames`, `fill_gaps` |
  363. Every call takes the grouped form — the tool name is the group, and the
  364. operation goes in `action`:
  365. ```json
  366. { "action": "validate_timeline", "args": { "filepath": "/path/to/project.fcpxml" } }
  367. ```
  368. ---
  369. ## Tools
  370. As of v0.19.0, the MCP tool list Claude sees by default is **15 grouped
  371. verbs**, not 102 flat tool names:
  372. | Group | Covers |
  373. |-------|--------|
  374. | `inspect` | Read-only understanding — stats, clips, markers, keywords, EDL/CSV, pacing, keyframes |
  375. | `diagnose` | Finding problems — flash frames, gaps, duplicates, health score |
  376. | `edit` | Changing clips — markers, trim, reorder, transitions, speed, split, silence removal, keyframes |
  377. | `mark` | Markers and chapters — batch add, SRT/VTT import, beat import |
  378. | `generate` | Building new structure — rough cuts, montages, A/B roll, templates |
  379. | `transcript` | Local Whisper transcription and transcript-driven cuts; `transcript_pack` puts the whole shoot on one page; `backend: elevenlabs` opts into speaker labels and audio events (audio leaves the machine) |
  380. | `deliver` | Getting the timeline out — NLE export, reformat, relink, push-to-FCP |
  381. | `preview` | **Seeing** the edit — a 720p proxy (timecode and names burned in on request), a labelled contact sheet of every clip, and a filmstrip+waveform check read from the SOURCE MEDIA; every picture comes back inline |
  382. | `watch` | Closing the round-trip — notice the operator's Cmd-E export and diff it against the last one |
  383. | `index` | The analysis cache — status with its age, warm every source in a timeline, clear. Nothing depends on it; `FCP_MCP_INDEX=off` and every tool still answers, only slower |
  384. | `scenes` | Shot boundaries from the pixels — list cuts per clip in source and timeline time, drop a marker on each, or split the clips there. PySceneDetect when installed, ffmpeg otherwise |
  385. | `organize` | Library housekeeping — bulk keywords, ratings and roles over a clip selection; `organize_auto` proposes keywords from captions and transcripts; `history` reads the operation ledger and `undo` moves the last outputs aside (never deletes) |
  386. | `find` | "Find the shot where…" — a router over transcript words, metadata and offline vision captions that names the tier on every hit; `find_index` warms every source; `find_to_timeline` assembles the hits into a selects reel |
  387. | `view` | **See the cut inline** — `view_timeline` returns the timeline as an exact rational-time payload that MCP Apps hosts render as an interactive timeline (`ui://fcp/timeline`); `view_clip` is the inspect button. Read-only |
  388. | `gen` | **Generative fill behind a money gate** — `gen_quote` prices a job (fal Kling/Wan, Gemini Omni Flash; Runway/Luma honest stubs); `gen_fill_gap` / `gen_broll` / `gen_extend_clip` refuse without `quote_id` + `confirm=true`, a key, and a price under `FCP_MCP_GEN_MAX_USD`; the result is ffprobed, attached as a `generated` lane clip with a marker, DTD-checked and journaled |
  389. Each call has the same shape: `{"action": "trim_clip", "args": {...}}`. The
  390. `action` is one of the 102 operation names below; `args` is whatever that
  391. tool always took. The group dispatches straight into the same handler — the
  392. behavior is identical, only the schema Claude sees up front is smaller. An
  393. unknown or cross-group action returns an error listing the valid actions for
  394. that group, so a wrong guess is recoverable in one turn.
  395. **Grouping is what's advertised, not what's callable.** `call_tool` resolves
  396. every one of the 102 operation names from a handler registry that doesn't care
  397. what `list_tools` chose to show — an existing MCP config that calls `trim_clip`
  398. directly keeps working with no changes. If you'd rather also see the flat tool
  399. schemas (e.g. for debugging, or a client that doesn't like the grouped shape),
  400. set:
  401. ```bash
  402. FCP_MCP_LEGACY_TOOLS=1
  403. ```
  404. This advertises the 71 flat schemas alongside the 15 groups — 86 tools in
  405. total. The 31 operations that were born as group actions (`preview`, `watch`,
  406. `index`, `scenes`, `organize`, `find`, plus `import_edl_json`) have no flat
  407. schema and are reached through their group.
  408. The flat tools will not be removed before a 1.0 release.
  409. ### See the timeline before you touch it
  410. Reading the `preview://<path>` MCP resource (any FCPXML path the server can
  411. already reach) returns the `view` app below with the timeline inlined, served
  412. as `text/html`: the same lanes, ruler, markers and timecodes, drawn at once in
  413. any browser or resource viewer with no host and no fetch. Outside an MCP Apps
  414. host it is read only; the edit buttons wait for one. (Until 0.32 this was a
  415. separate static render; there is now one timeline picture.)
  416. ![Timeline preview: a 30-second gym-session cut as the preview:// page draws it in 0.34, the whole cut in the track: an overview minimap, four chapter markers on the ruler, a red flash flag one frame before Press, grey lane tags, a Bench clip connected on lane 1, six storyline clips each named inside, with a filmstrip over its own waveform band and a blue role stripe, a translucent cross dissolve into Finish, on a true-black page](docs/assets/timeline-preview.png)
  417. *A 30-second gym-session cut (`demo/fixtures/gym_session.py`: the author's own
  418. footage, with synthesised tones for sound), drawn from its FCPXML and its
  419. media at 1440 px, dark: the whole cut in the track, every clip named inside,
  420. the filmstrip over each clip's waveform band (one -60..0 dBFS scale), the
  421. 1-frame flash before Press in red, the 0.5 s cross dissolve over the cut into
  422. Finish. `scripts/readme_timeline.py` refuses to save it when a clip has no
  423. filmstrip or waveform or a marker is missing.*
  424. ### Proof you can read (v0.32.0)
  425. Every picture the preview tools make carries the edit's names, timecodes and
  426. cuts, drawn by the server (one bundled bitmap font, no Pillow, no ffmpeg
  427. `drawtext`), and comes back as an MCP image block beside its path, so the
  428. model reads the cut instead of being told about it. Each one is sized for
  429. Claude's vision input: long edge at most 1,568 px and at most 1,568 patches of
  430. 28 px ([vision docs](https://platform.claude.com/docs/en/build-with-claude/vision),
  431. "Resolution and token cost", read 2026-11-13), capitals at least 14 px tall
  432. where they are seen, at most 12 frames a page. Lengths are whole frames
  433. everywhere they add up (`121f`): a start plus a length is the next start.
  434. Ranges are in-out with the out-point exclusive, as Final Cut's are, and the
  435. length after them (`00:00:05:01–00:00:06:11 · 34f`). One colour rule on
  436. every picture: cyan text is a record time and cyan marks are the cut;
  437. source times are white or grey; red is a failure.
  438. Below, the same calls on the author's own gym session, 0.31.0 above each
  439. picture and 0.32.0 under it.
  440. **`preview_sheet`**: every video clip, connected ones badged with their lane
  441. (`#5 L1`) and saying what they play over (`over #4`), each with its length,
  442. record timecode and source in-point (the three takes of one lift told
  443. apart), the dissolve as a bowtie in the gutter on its cut and a `dissolve
  444. 12f in` line; one red badge per flash, as diagnose counts it, on the card
  445. whose picture flashes (`flash 1f 00:00:20:03 · src 00:00:17:23`), the clip
  446. that ends early saying so (`ends 1f before #6`) and two cards that show the
  447. same frames saying that too (`dup 66f with #5`); and a header with the
  448. duration, frame rate, clip count and the file's `sha256` prefix. `layout: "phone"` draws two columns for a
  449. 390 px screen (shown here); a page that does not hold every clip says where
  450. the rest are.
  451. ![preview_sheet before and after: 0.31.0's six loose unlabelled frames above 0.32.0's phone sheet with numbers, names, lengths, record and source timecodes](docs/screenshots/2026-11-13_before-after-sheet-032.png)
  452. **`preview_check`**: the source media in two bands, each its frames over its
  453. own ruler and its own waveform on that band's time axis, as Final Cut stacks
  454. a filmstrip over a waveform; ruler labels hang from their ticks. With
  455. `filepath`, what the edit removed is dimmed and drawn as a grey bar on the
  456. ruler, the cut's out-point is marked on its band and its in-point on its
  457. own, and under a rule, off the band grid, the join as played: the last and
  458. first kept frames side by side, each captioned with where it plays and what
  459. it is in the file (`rec 00:00:10:00` over `src 00:00:05:00`), the removed
  460. range with its length and how much of the silence the edit kept each side,
  461. read from the edit. The waveform is rectified, RMS over peak in dB, with 0,
  462. -20 and -40 dB labelled at the band's edge, each label centred on its tick,
  463. and the dashed line labelled with the threshold the silence detector used
  464. (`-40 silence`); silences are named with their length (and, in the next
  465. band, where they end), and no label sits on a line.
  466. ![preview_check before and after: 0.31.0's untimed strip and flat bar above 0.32.0's two bands with rulers, removed frames, the cut pair and dB levels](docs/screenshots/2026-11-13_before-after-check-032.png)
  467. **`preview_render`**: 1280x720 by default, a poster frame inline and a link
  468. to the MP4. `burn_in: true` writes a second file with one opaque chip on
  469. every frame, inside 5% action safe: the record time and frame (`REC
  470. 00:00:18:00 · f432`), what is on screen, top layer first, its source file and
  471. timecode, and the source of the clip it covers (`over Squat.mov
  472. 00:00:15:20`), added after the lane check has read the clean render. 0.31.0's frame is from a render that
  473. had fallen back: a dissolve after hard cuts failed the full graph, so the
  474. dissolve was dropped and the sound with it (fixed in 0.32.0).
  475. ![preview_render before and after: 0.31.0's 854x480 frame above 0.32.0's 1280x720 frame burned with REC 00:00:18:00 Bench (L1) over Squat and SRC Bench.mov 00:00:00:21](docs/screenshots/2026-11-13_before-after-proxy-032.png)
  476. **`detect_scenes`**: the frame before and the frame after each cut it finds,
  477. each with its own timecode, the detector's score against its threshold, and
  478. the scenes with their lengths. **`preview_frame`** with `burn: true` names the
  479. file, the source timecode and the frame number.
  480. ![detect_scenes before and after: 0.31.0's table of times above 0.32.0's before and after frames, scores and scene list](docs/screenshots/2026-11-13_before-after-scenes-032.png)
  481. **`preview_timeline`** prints the file's `sha256` prefix, a ruler, a legend,
  482. the markers, lanes above and below the spine, then an EDL whose every value
  483. sits under its own header: every clip in record order (`AV` for picture and
  484. sound, record in and out, length in frames, the transition into it as CMX
  485. writes it, `D 12f`, source file, source in and out), with the markers
  486. (`^`, name and kind in the note), the dissolve's span (`D`) and any flash in
  487. the picture (`!`) as rows at their place. **`validate_timeline`** leads
  488. with its verdict (`FAIL · 1 FAIL, 2 WARN, 1 INFO`), then reads by a ✓ PASS
  489. / ⚠︎ WARN / ✗ FAIL / · INFO column, what each check found, and where;
  490. checks flash frames in the composited PICTURE as well as clip lengths (a
  491. connected clip ending one frame before the next cut leaves a frame of the
  492. spine showing) and offers the fix the media allows first, with its cost;
  493. splits duplicate frames (WARN, with the record ranges where the shared
  494. frames play) from a reused source (INFO); checks transition handles against
  495. the real media, offline media, each source's frame rate and size
  496. against the sequence (a 3x upscale is a WARN), and each asset's clock against
  497. its file's timecode track (an asset Final Cut would put on another clock is a
  498. FAIL: its clips import empty, #45); names what it does not check
  499. (loudness, true peak, black or frozen frames, audio sync); counts only the
  500. checks that ran; and prints a fix only for what failed, as the grouped call
  501. that runs it. **`analyze_timeline`** gives edits and cuts per minute apart,
  502. the shortest picture actually on screen, the audio (channels and rate per
  503. file, measured), and every count diagnose prints.
  504. ### See the cut inline — the MCP Apps timeline (v0.26.0)
  505. The `view` tool turns the same timeline into something a host renders
  506. **inside the conversation**. Call `view` with `view_timeline` and a
  507. filepath; a host that speaks MCP Apps opens the `ui://fcp/timeline`
  508. resource in a sandboxed iframe and posts the result into it. Which hosts do
  509. that, and which get text, is in [Where the timeline draws](#where-the-timeline-draws).
  510. ![The MCP Apps timeline in 0.34 on an 18-minute two-camera interview: an overview minimap in role colours, a ruler with chapter, standard, to-do and completed marker glyphs each named, grey lane tags, the whole 18 minutes in the track, lower thirds as purple Titles bars above the camera cuts, each cut a filmstrip over its waveform band with a blue dialogue stripe, a music bed named Theme with a green stripe and whooshes with teal effects stripes below, a cyan playhead, and a compact selection panel](docs/screenshots/2026-11-15_034-interview-1440.png)
  511. *The app in headless Chromium, 1440 px, on `demo/fixtures/interview.py` (two
  512. synthetic cameras, 44 cuts, lower thirds, markers of all four kinds; ffmpeg
  513. test patterns and sine tones, no person). Light theme:
  514. `docs/screenshots/2026-11-15_034-interview-1440-light.png`. Phone width:
  515. `docs/screenshots/2026-11-15_034-interview-390.png`. The gym cut and the
  516. music video at 1440, 430 and 390 are beside them.*
  517. What it shows (one look since 0.34, open like Final Cut's timeline): the
  518. cut's fit region at open (the whole cut, or a music video's picture; at
  519. phone width a long cut zooms in to a 64 px median clip and scrolls), and an
  520. overview minimap of the whole cut (lanes in role colours, a tick per
  521. marker, the flash, a window round the part in view); every lane (the
  522. storyline, connected lanes above, sound lanes below, each connected clip
  523. with its stem and anchor dot on the storyline), with grey lane tags on a
  524. desktop; clips 88 px tall (titles and sound 72 px, every clip 56 px on a
  525. phone) with a filmstrip over the waveform's own band (one -60..0 dBFS
  526. scale, a column per peak), and a 3 px stripe in Final Cut 12.4's own role
  527. colour (read from the installed app by `scripts/fcp_role_colours.m`, the
  528. same in both themes); titles in the Titles colour; transitions as an
  529. overlay filled with the transition's colour, named in the ruler; a glyph per
  530. marker kind (standard, chapter, an open square for a to-do, a filled one
  531. with a check for a completed to-do), always with its name, or in a bracketed run where the names
  532. cannot all fit; gaps; a flash frame in red, the only red; a timecode ruler
  533. with frame ticks and a playhead on top that snaps to cuts; no mark drawn
  534. over another (the playhead, once moved, is a cursor over them). A clip's name is inside it, whole, or not drawn, and
  535. the hint strip counts the names shown ("4 of 58 names shown · tap or zoom"
  536. on the interview at 390); a tap shows a clip's name, start and length in a strip above the
  537. ruler, the record times in cyan. Click a clip for its details; drag on the ruler for a range. It
  538. follows the host's theme, then the OS's. The buttons call back into the
  539. server through the host: **Inspect** (`view_clip`) and **Find similar
  540. shots** (`find_shots`) are reads; **Add marker at playhead** (`mark`) and
  541. **Delete clip** (`edit`) are the ordinary edit actions, so the journal, the
  542. project guard and the review gate apply exactly as they do from chat, and
  543. the app re-renders from the new output file when the edit returns.
  544. The payload is exact: every position and duration is a
  545. `numerator/denominator` string straight from the model's Fractions, and
  546. the tests round-trip both fixtures through it. It travels as the result's
  547. `structuredContent`, which the MCP Apps spec hands to the app and keeps out
  548. of the model's context; a host without MCP Apps gets the summary and the
  549. clips in record order as text.
  550. The shell loads nothing from the network. Two honest limits: the in-iframe
  551. protocol (`ui/initialize`, `ui/notifications/tool-result`, `tools/call`)
  552. follows the spec text and the `@modelcontextprotocol/ext-apps` client and
  553. has been driven by the official `ext-apps` reference host and a stub host,
  554. and is not yet captured in Claude Desktop; and on `mcp` 1.x
  555. the tool carries `_meta.ui` and the resource is served, but the SDK has no
  556. slot to advertise the extension capability, so a host that insists on the
  557. handshake needs `mcp` 2.x.
  558. ### Generative fill — quote, then confirm, then insert (v0.26.0)
  559. The `gen` tool fills a gap, adds B-roll over a clip, or extends a clip past
  560. its out point with generated video. **It spends money, so the order is
  561. fixed and the gate is not optional:**
  562. ```json
  563. gen {"action": "gen_quote", "args": {"provider": "fal", "seconds": 7, "prompt": "a street at dusk, handheld"}}
  564. → Quote 61585b429a17 — fal/kling-2.5, 10s billable for 7.00s requested
  565. Estimated: $0.70 (prices as of 2026-11-12, 0 days ago; read on the vendor's own page; third-party figures, NOT verified against an invoice)
  566. Cap: $5 per call (FCP_MCP_GEN_MAX_USD)
  567. gen {"action": "gen_fill_gap", "args": {"filepath": "…/cut.fcpxml", "prompt": "a street at dusk, handheld",
  568. "seconds": 7, "quote_id": "61585b429a17", "confirm": true}}
  569. ```
  570. Generation refuses — naming the fix each time — without `confirm=true`,
  571. without a quote id, with a quote whose job changed (the quote is recomputed
  572. from provider, model, billable seconds and prompt; a stale id cannot buy a
  573. different job), without the provider's key in the environment, and above
  574. the per-call cap `FCP_MCP_GEN_MAX_USD` (default `5`). Kling and Wan bill 5
  575. or 10 seconds, so a 7-second gap is a 10-second job and the quote says 10;
  576. Gemini Omni 1.2 Flash makes 3 to 15 second clips and is quoted as at least
  577. one 10-second call (11 to 15 s quoted as 15). Prices are the upper end of
  578. what each provider's own page said on `prices_as_of` (2026-11-12): every
  579. quote names its source page, says how many days old the table is, and prints
  580. UNVERIFIED for a figure no vendor page states. None is checked against an
  581. invoice, and a test fails the daily CI run when the table is over 45 days
  582. old.
  583. Providers: `fal` (`kling-2.5` default, `wan-2.5`) and `gemini` (`omni-1.2-flash`)
  584. generate; `runway` (Aleph 2.0) and `luma` (Ray Modify) are video-to-video and
  585. quote but refuse as not implemented rather than pretend. Keys come from
  586. `FAL_KEY`, `GEMINI_API_KEY`, `RUNWAY_API_KEY`, `LUMA_API_KEY` only, travel in
  587. one auth header, are never written or logged, and every reply is redacted;
  588. the transport refuses to send a key in a URL or body. What comes back is
  589. ffprobed for its **real** duration and frame rate (the model never invents
  590. an fps), saved under `generated/` beside the project through the sandboxed
  591. output path so the journal records it, attached as a connected clip with
  592. `videoRole="generated"` and a marker naming prompt and provider, snapped to
  593. the sequence's frame grid, DTD-validated, and reported with the output
  594. file's sha256. `gen_broll` and `gen_extend_clip` condition the generation on
  595. a frame of the source clip when the media is present and say so when it is
  596. not.
  597. ### Claude Code skill
  598. A `final-cut-pro` skill ships in `skill/`, wrapping this server with the
  599. workflow order (`inspect` → `diagnose` → read `preview://` → `edit`) and the
  600. FCPXML gotchas that don't fit in a tool description. Install it alongside the
  601. MCP server:
  602. ```bash
  603. git clone https://github.com/DareDev256/fcp-mcp-server
  604. ln -s "$PWD/fcp-mcp-server/skill" ~/.claude/skills/final-cut-pro
  605. ```
  606. ---
  607. ## All 102 Operations
  608. The 102 operations below are what the 15 groups in [Tools](#tools) dispatch
  609. to — every `action` value the groups accept. The 71 flat-schema operations are
  610. still callable directly with `FCP_MCP_LEGACY_TOOLS=1`.
  611. | Category | Tools | What It Does |
  612. |----------|------:|--------------|
  613. | **Analysis** | 11 | Stats, clips, markers, keywords, EDL/CSV, pacing |
  614. | **Multi-Track** | 3 | Connected clips, compound clips, secondary lanes |
  615. | **Roles** | 4 | List, assign, filter, export stems |
  616. | **QC & Validation** | 4 | Flash frames, duplicates, gaps, health score |
  617. | **Keyframes** | 5 | Read, set, delete and batch-edit intrinsic keys; author adaptive Bezier paths and easing; [usage and limits](docs/keyframes.md) |
  618. | **Speed Curves** | 3 | Inspect, set and reset variable speed; [usage and limits](docs/retiming.md) |
  619. | **Editing** | 9 | Markers, trim, reorder, transitions, speed, split |
  620. | **Batch Fixes** | 3 | Auto-fix flash frames, rapid trim, fill gaps |
  621. | **Comparison** | 1 | Diff two timelines — added/removed/moved/trimmed |
  622. | **Reformat** | 1 | Aspect ratio conversion (9:16, 1:1, 4:5, custom) |
  623. | **Silence** | 2 | Detect and remove silence candidates (XML heuristics) |
  624. | **Media Intelligence** | 3 | Real silence detection + auto-removal (ffmpeg), musical beat detection (librosa) |
  625. | **NLE Export** | 2 | DaVinci Resolve v1.9, FCP7 XMEML v5 |
  626. | **Generation** | 3 | Rough cuts, montages, A/B roll |
  627. | **Beat Sync** | 2 | Import beat markers, snap cuts to beats |
  628. | **Import** | 3 | SRT/VTT subtitles, YouTube chapters → markers; video-use `edl.json` → FCPXML |
  629. | **Audio** | 1 | Add audio clips, music beds at any lane |
  630. | **Compound** | 2 | Create/flatten compound clips |
  631. | **Templates** | 2 | Pre-built timeline structures (intro/outro, lower thirds, music video) |
  632. | **Effects** | 1 | List FCP transition effects with UUIDs |
  633. | **Media** | 1 | Bulk relink moved/renamed media (rewrite `media-rep` src paths) |
  634. | **Transcript Intelligence** | 4 | Local Whisper transcription, transcript-driven cuts, filler-word removal, the one-page transcript pack |
  635. | **Live (macOS)** | 2 | Push FCPXML into the running FCP (zero-click Apple-event import); list open libraries |
  636. | **Preview** | 5 | Proxy render (burn-in, poster), labelled contact sheet, single frame, filmstrip+waveform check from the source media, text timeline; pictures inline as image blocks |
  637. | **Watch** | 4 | Start/status/stop an export watch folder; pull the latest export and diff it |
  638. | **Index** | 3 | Analysis cache status (with age), build, clear |
  639. | **Scenes** | 3 | Detect shot boundaries, mark them, split on them |
  640. | **Organize** | 6 | Bulk keywords/ratings/roles, auto-proposed keywords, operation history, hash-checked undo |
  641. | **Find** | 3 | Shot search across transcript, metadata and vision tiers; warm the index; assemble a selects reel |
  642. | **View** | 2 | The MCP Apps timeline payload (`view_timeline`) and the clip inspector (`view_clip`) |
  643. | **Generative fill** | 4 | Quote a job, then fill a gap, add B-roll or extend a clip against a confirmed quote |
  644. | | **102** | |
  645. <details>
  646. <summary><strong>Full tool reference (click to expand)</strong></summary>
  647. #### Analysis — 11 tools
  648. `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`
  649. #### Multi-Track — 3 tools
  650. `list_connected_clips` · `add_connected_clip` · `list_compound_clips`
  651. #### Roles — 4 tools
  652. `list_roles` · `assign_role` · `filter_by_role` · `export_role_stems`
  653. #### QC & Validation — 4 tools
  654. `detect_flash_frames` · `detect_duplicates` · `detect_gaps` · `validate_timeline`
  655. #### Editing — 9 tools
  656. `add_marker` · `batch_add_markers` · `insert_clip` · `trim_clip` · `reorder_clips` · `add_transition` · `change_speed` · `delete_clips` · `split_clip`
  657. #### Batch Fixes — 3 tools
  658. `fix_flash_frames` · `rapid_trim` · `fill_gaps`
  659. #### Comparison · Reformat · Silence
  660. `diff_timelines` · `reformat_timeline` · `detect_silence_candidates` · `remove_silence_candidates`
  661. #### NLE Export — 2 tools
  662. `export_resolve_xml` (DaVinci Resolve FCPXML v1.9) · `export_fcp7_xml` (Premiere Pro / Resolve / Avid XMEML v5)
  663. #### Generation — 3 tools
  664. `auto_rough_cut` · `generate_montage` · `generate_ab_roll`
  665. #### Beat Sync — 2 tools
  666. `import_beat_markers` · `snap_to_beats`
  667. #### Import — 3 tools
  668. `import_srt_markers` · `import_transcript_markers` (supports SMPTE `HH:MM:SS:FF` with frame-accurate placement) · `import_edl_json` (video-use `{sources, ranges, grade?}` → FCPXML; `ranges[].source` is a key into `sources`, not a path — *v0.17.0*; each source on its file's timecode clock — *v0.33.0*)
  669. #### v0.6.0 — Audio, Compound, Templates, Effects — 6 tools
  670. `list_effects` · `add_audio` · `create_compound_clip` · `flatten_compound_clip` · `list_templates` · `apply_template`
  671. #### v0.8.0 — Media — 1 tool
  672. `relink_media` (bulk-rewrite `asset`/`media-rep` src paths with `dry_run` preview — relink a moved drive without opening FCP)
  673. #### v0.10–0.12 — Media Intelligence — 3 tools
  674. `detect_media_silence` (analyzes each clip's real source audio with ffmpeg silencedetect and maps silence spans into timeline time) · `remove_media_silence` (cuts detected silence out of the timeline with ripple — clips split around silence, padding keeps edits breathing, non-destructive output) — both require ffmpeg, degrade gracefully without it · `detect_beats` (musical beat + tempo detection via librosa, writes a beats JSON that chains into `import_beat_markers` + `snap_to_beats`; needs the optional `[intelligence]` extra)
  675. #### v0.13.0 / v0.18.0 — Transcript Intelligence — 4 tools
  676. `transcribe_media` · `edit_by_transcript` · `remove_filler_words` · `transcript_pack` (v0.18.0 — one page of everything said; every one of the four takes `backend: "elevenlabs"` for speakers and audio events)
  677. #### v0.9.0 — Live Mode (macOS + Final Cut Pro) — 2 tools
  678. `push_to_fcp` (zero-click FCPXML import into the running FCP via Apple event) · `list_fcp_libraries` (enumerate open libraries/events/projects)
  679. #### v0.17.0 — Preview — 5 group actions
  680. `preview_render` · `preview_sheet` · `preview_frame` · `preview_check` · `preview_timeline`
  681. Since v0.28.0 the proxy is exactly as long as the timeline, and every instant
  682. of it is the timeline's own picture or a black substitute the report names.
  683. A transition becomes an ffmpeg `xfade` (dissolve, dip to colour, wipe, slide)
  684. drawn on the clips' handles the way Final Cut draws it, so it moves nothing;
  685. gaps keep their time; stills loop; timecoded media is read on its own clock;
  686. connected clips are placed by their resolved timeline position and drawn at
  687. their conform, scale and position on a canvas of the sequence's shape. A clip
  688. whose file has no picture where the timeline needs one is shown black or left
  689. off its lane, by name, instead of failing the render. After rendering, the
  690. artifact's own duration is read back against the timeline and each lane clip
  691. is looked for in the frame (`Seen in the render` / `NOT drawn`), so "drawn"
  692. is a measurement. Since v0.30.0 the proxy has sound too: every clip's audio is placed at its
  693. timeline instant over a silent bed the timeline's length, crossfaded at
  694. transitions, with `adjust-volume` applied, and the file's audio track is
  695. checked like its picture. What the proxy cannot render is printed with it:
  696. crop, corner pin, blend modes, effects, rotation, keyframed transforms,
  697. titles, pan, EQ and audio effects. Since v0.32.0 the proxy is 1280x720 by
  698. default and every preview picture is labelled and returned inline (see
  699. "Proof you can read" above).
  700. #### v0.17.0 — Watch — 4 group actions
  701. `watch_start` · `watch_status` · `watch_stop` · `watch_pull`
  702. #### v0.18.0 — Index — 3 group actions
  703. `index_status` · `index_build` · `index_clear`
  704. #### v0.18.0 — Scenes — 3 group actions
  705. `detect_scenes` · `scenes_to_markers` · `scenes_split`
  706. #### v0.19.0 — Organize — 6 group actions
  707. `organize_keywords` (add / remove / replace over a selection by glob name, keyword or role) · `organize_rate` (favorite / rejected / clear) · `organize_roles` · `organize_auto` (proposes keywords from cached captions and transcripts; never transcribes; `apply=true` writes) · `history` (the operation ledger as a table with ages) · `undo` (moves the last N recorded outputs to `<journal>/undone/` — never deletes, refuses on hash mismatch)
  708. #### v0.19.0 — Find — 3 group actions
  709. `find_shots` (tiered router — transcript, metadata, vision — with the tier and a `why` on every hit; at most 20 live captions per call) · `find_index` (warm transcripts, scenes and opt-in captions for every source, reporting each as done / skipped / unavailable) · `find_to_timeline` (assemble the hits into a `_found` selects reel under the diversity constraint)
  710. </details>
  711. ---
  712. ## Environment Variables
  713. | Variable | Required | Default | Description |
  714. |----------|----------|---------|-------------|
  715. | `FCP_PROJECTS_DIR` | No | `~/Movies` | Root directory for FCPXML discovery via `list_projects`. Confines **listing only** — it does not restrict which files you can open |
  716. | `FCP_PROJECTS_DIRS` | No | unset | Sandbox roots, separated like `PATH` (`:` on macOS/Linux) — e.g. `~/Movies:/Volumes/Scratch/Projects`. This is the **only** variable that confines reads, and it is fully opt-in. Symlinked library media (Final Cut's default "leave files in place" import) stays readable |
  717. | `FCP_MAX_DISCOVERY_FILES` | No | `10000` | Cap on files collected by one `list_projects` directory walk. The walk stops at the cap and the result says it is incomplete |
  718. | `FCP_MAX_BATCH_MARKERS` | No | `10000` | Cap on markers written by one batch or import operation. Excess markers are reported as dropped, never silently skipped |
  719. | `FCP_MAX_TRANSCRIPT_CHARS` | No | `1048576` | Cap on inline transcript text passed to `import_transcript_markers` |
  720. | `FCPXML_DTD_DIR` | No | FCP app bundle | Directory of Apple `FCPXMLv*_*.dtd` files for DTD validation (auto-detected from the installed Final Cut Pro) |
  721. | `FCP_MCP_LEGACY_TOOLS` | No | unset | Set to `1` to advertise the 71 flat tool schemas alongside the 15 grouped tools |
  722. | `FCP_WATCH_DIR` | No | unset | Default folder `watch_start` observes for Final Cut Pro XML exports |
  723. | `FCP_MCP_AUTOPUSH` | No | unset | Set to `1` so every write also imports into the running Final Cut Pro. Off by default — repeated imports accumulate library churn, which is your call to make |
  724. | `FCP_MCP_INDEX` | No | `~/.fcp-mcp/index.db` | Where the analysis cache lives. `off` disables it entirely; every tool still works, it just recomputes. Any other value is a path |
  725. | `ELEVENLABS_API_KEY` | No | unset | Enables `backend: "elevenlabs"` on the transcript tools. Sent as the `xi-api-key` header and nowhere else; never read unless that backend is requested |
  726. | `FCP_MCP_JOURNAL` | No | `~/.fcp-mcp/journal/` | Where the operation ledger lives (paths and hashes, never content). `off` disables it — `history`/`undo` then say so and the `deliver` review gate refuses to certify anything |
  727. | `FCP_MCP_VLM_MODEL` | No | `mlx-community/Qwen2-VL-2B-Instruct-4bit` | Hub id of the MLX vision model `find` captions shots with. Loaded offline only; a missing model is reported with its `hf download` command, never fetched |
  728. | `FCP_MCP_GEN_MAX_USD` | No | `5` | Per-call ceiling on the estimated cost of a `gen` generation. A quote over it says so; generation refuses. A malformed value raises rather than defaulting |
  729. | `FAL_KEY` | No | unset | Enables `gen` provider `fal` (Kling 2.5, Wan 2.5). Sent as `Authorization: Key …` to queue.fal.run only; never read unless a `gen` action runs |
  730. | `GEMINI_API_KEY` | No | unset | Enables `gen` provider `gemini` (Gemini Omni 1.2 Flash; Omni 1.1 routes to it from 2026-12-03 and Veo 3.1 preview left the Gemini API on 2026-10-22). Sent as `x-goog-api-key` to generativelanguage.googleapis.com only |
  731. | `RUNWAY_API_KEY`, `LUMA_API_KEY` | No | unset | Reserved for the video-to-video providers, which quote but are not implemented in this release |
  732. ---
  733. ## Compatibility
  734. | Component | Supported Versions |
  735. |-----------|--------------------|
  736. | FCPXML format | reads v1.8 – v1.14 · writes v1.13 (modified files keep their source version) |
  737. | Final Cut Pro | **for Mac** 10.4+ through 12.4 (the newest release, 2026-09-29, per Apple's notes, checked 2026-11-12) · flat `.fcpxml` and `.fcpxmld` bundles (sidecars preserved). Final Cut Pro for iPad has no documented FCPXML import or export, so it is not supported |
  738. | Python | 3.10, 3.11, 3.12 |
  739. | MCP protocol | Spec versions are dates; the installed `mcp` SDK negotiates one. `mcp` 1.28.1 speaks up to 2025-11-25 and `mcp` 2.3.0 up to 2026-07-28, the current spec (checked 2026-11-12) |
  740. | `mcp` SDK | 1.21.1 through 2.x — both the decorator API and the `add_request_handler` API that replaced it. CI tests the declared floor and 2.x on every push |
  741. | **Export targets** | |
  742. | → DaVinci Resolve | FCPXML v1.9 |
  743. | → Premiere Pro / Avid | FCP7 XMEML v5 |
  744. ---
  745. ## Architecture
  746. ```
  747. fcp-mcp-server/ ~15.7k lines Python
  748. ├── server.py MCP entry point — 15 grouped tools advertised by default
  749. │ (TOOL_GROUPS), dispatching into 102 handlers
  750. │ (TOOL_HANDLERS); 5 prompts, resource discovery.
  751. │ FCP_MCP_LEGACY_TOOLS=1 re-advertises the flat tools.
  752. │ Binds itself to tools/ via bind_server() — group modules
  753. │ must never `import server` (it runs as __main__).
  754. ├── tools/ New tool groups, registered without growing server.py
  755. │ ├── __init__.py EXTRA_GROUPS/EXTRA_HANDLERS registry + bind_server()
  756. │ ├── _common.py text_result / parse_project through the bound module
  757. │ ├── preview.py preview group — render, sheet, frame, check, timeline
  758. │ ├── watch.py watch group — start, status, stop, pull
  759. │ ├── index.py index group — status (with age), build, clear
  760. │ ├── scenes.py scenes group — detect, to_markers, split
  761. │ ├── organize.py organize group — keywords, rate, roles, auto, history, undo
  762. │ ├── find.py find group — shots (tiered router), index, to_timeline
  763. │ └── nle.py NLE export, effects, audio, compound clips, templates,
  764. │ relink — moved out of server.py, re-exported by it
  765. │ _resolve_io_paths() / _setup_modifier() / _setup_generator()
  766. │ _format_clip_table() / _markdown_table() / _format_batch_result()
  767. │ _raw_markers_to_batch()
  768. │ _detect_flash_frames() / _detect_gaps() / _detect_duplicate_groups()
  769. │ consolidate path validation, QC detection, rendering, handler boilerplate
  770. ├── fcpxml/
  771. │ ├── journal.py Append-only operation ledger — paths + hashes, never content;
  772. │ │ undo is a pointer move into undone/, refused on hash mismatch
  773. │ ├── find.py Pure ranking over transcript words and metadata ranges, tier named
  774. │ ├── vlm.py Offline MLX shot captions — HF offline flags set BEFORE import.
  775. │ │ Captions a 1080p frame: vision tokens scale with pixel area
  776. │ ├── diversity.py Source-separation constraint + diversity score for assemblies
  777. │ ├── index.py SQLite analysis cache — keyed (path, mtime, size), num/den time,
  778. │ │ rebuilt on corruption; NEVER a source of truth (CI runs it off)
  779. │ ├── progress.py Per-clip MCP progress notifications on either SDK
  780. │ ├── scenes.py Shot boundaries — PySceneDetect or ffmpeg's coarser scene filter
  781. │ ├── transcript_pack.py Every transcript on one page; byte-measured 60KB cap
  782. │ ├── transcribe.py Local faster-whisper, or ElevenLabs Scribe opt-in (speakers, events)
  783. │ ├── filtergraph.py Timeline → ffmpeg graph. PURE — Fraction end to end,
  784. │ │ so compilation is asserted without ffmpeg installed.
  785. │ │ Output time IS timeline time: handle-drawn xfades,
  786. │ │ gaps, stills, asset clocks, conform + transform; what
  787. │ │ it cannot honour is reported, never silently dropped
  788. │ ├── render.py Probes every source, executes the graph with fallbacks,
  789. │ │ reads the artifact's OWN duration back and looks for
  790. │ │ every lane clip in the frame
  791. │ ├── proofs.py The labelled pictures: contact sheet, filmstrip + waveform
  792. │ │ check from SOURCE MEDIA, scenes strip, burn-in, text timeline
  793. │ ├── raster.py Pure-Python raster + the bundled bitmap font; text read back
  794. │ │ off pixels for the gates; the vision budget
  795. │ ├── fonts/ Spleen 12x24 and 16x32 (BSD-2-Clause, licence beside them)
  796. │ ├── watchfolder.py Export detection. Digests CONTENT, not (mtime, size)
  797. │ ├── bridges.py SpliceKit :9876 / CommandPost :27480 — DETECTION ONLY
  798. │ ├── edl.py video-use edl.json → FCPXML
  799. │ ├── models.py TimeValue, Timecode, Clip, ConnectedClip, MarkerType, Timeline
  800. │ ├── parser.py FCPXML → Python (spine, connected clips, roles, markers)
  801. │ ├── writer.py Modify & write (markers, trim, gaps, transitions, silence)
  802. │ │ FCPXMLModifier: index-based editing (clips/resources/formats dicts)
  803. │ │ FCPXMLWriter: generate new FCPXML from Python objects
  804. │ │ Helpers: _resolve_asset, _absorb_into_neighbor, _ripple_from_index
  805. │ ├── rough_cut.py Generate timelines (rough cuts, montages, A/B roll)
  806. │ ├── diff.py Timeline comparison engine (identity matching, threshold docs)
  807. │ ├── export.py DaVinci Resolve v1.9 + FCP7 XMEML v5 export
  808. │ ├── media_intel.py Real media analysis — audio silence detection via bounded ffmpeg subprocess
  809. │ ├── safe_xml.py Centralized defusedxml wrappers (XXE/entity-bomb protection) + serialize_xml()
  810. │ ├── dtd.py Validate output against Apple's official DTDs (located in the FCP app bundle)
  811. │ └── templates.py Template system (intro/outro, lower thirds, music video)
  812. ├── skill/ final-cut-pro Claude Code skill wrapping this server
  813. ├── tests/ 2708 tests across 97 suites (collected 2026-11-13) — see Testing below
  814. │ ├── test_models.py TimeValue math, Timecode formatting, MarkerType contracts
  815. │ ├── test_parser.py FCPXML parsing, connected clips, edge cases
  816. │ ├── test_writer.py Clip editing, marker writing, speed changes
  817. │ ├── test_fcpxml_writer.py FCPXMLWriter generation from Python objects
  818. │ ├── test_server.py MCP tool handlers, dispatch, path validation
  819. │ ├── test_rough_cut.py Rough cut generation, montage, A/B roll
  820. │ ├── test_diff.py Moved clips, transitions, markers, clip identity
  821. │ ├── test_export.py Attribute stripping, compound flattening, audio tracks
  822. │ ├── test_features_v05.py Multi-track, roles, diff, reformat, export
  823. │ ├── test_features_v06.py Audio, compound clips, templates, effects, validation
  824. │ ├── test_marker_pipeline.py Marker builder, batch modes, output format
  825. │ ├── test_speed_cutting.py Speed cutting, montage config, pacing curves
  826. │ ├── test_security.py Input validation, XML sanitization, XXE protection
  827. │ ├── test_edge_cases.py Boundary arithmetic, clip collisions, split/diff edges
  828. │ ├── test_diversity.py Boundary conditions across diff, models, validation
  829. │ ├── test_refactored_helpers.py _index_elements, _iter_spine_clips, serialize_xml edges
  830. │ ├── test_targeted_gaps.py Targeted branch coverage for diff, export, models
  831. │ ├── test_bundles.py .fcpxmld bundles, sidecar preservation, FCPXML 1.13/1.14 tolerance
  832. │ ├── test_relink.py Bulk media relink (URL + plain paths, dry run, segment matching)
  833. │ ├── test_media_intel.py silencedetect parsing, timeline mapping, real-WAV integration, handler
  834. │ ├── test_transcribe.py Phrase/filler span matching, range merge/invert algebra, Whisper handlers
  835. │ ├── test_validation.py Pydantic input validation models
  836. │ ├── test_live.py push_to_fcp / list_fcp_libraries (Apple events, mocked + live-gated)
  837. │ ├── test_tool_groups.py TOOL_GROUPS dispatch to the TOOL_HANDLERS, legacy flag, schema size
  838. │ ├── test_index*.py The cache: invalidation, rebuild, wiring, and the index group
  839. │ ├── test_scenes*.py Shot boundaries on synthesised colour bars; the scenes group
  840. │ ├── test_transcript_pack*.py The one-page pack and its handler
  841. │ ├── test_transcribe_scribe.py Scribe backend with urlopen patched; key-leak mutation check
  842. │ ├── test_preview.py preview:// serves the app with the timeline inlined
  843. │ ├── test_proofs.py The 0.32 gates: timecodes read back off the PNGs and every
  844. │ │ burned frame, ticks to a pixel, legibility, image blocks
  845. │ ├── test_skill.py final-cut-pro skill structure
  846. │ └── test_dtd_validation.py Output validated against Apple's shipped DTDs (skips without FCP)
  847. ├── docs/
  848. │ ├── WORKFLOWS.md 8 production workflow recipes
  849. │ └── CAPABILITY-AUDIT-2026-06.md Ecosystem audit + dual-mode (XML + Live) roadmap
  850. └── examples/
  851. └── sample.fcpxml 9 clips, 24fps — test fixture
  852. ```
  853. ---
  854. ## Security
  855. Every tool handler is hardened against adversarial input — critical for MCP servers where prompts may be LLM-generated, not human-typed.
  856. Found a vulnerability? Report it privately via the repo's **Security → Report a vulnerability** tab — see [SECURITY.md](SECURITY.md).
  857. | Layer | Protection |
  858. |-------|------------|
  859. | **File I/O** | Path traversal blocked, null bytes rejected, symlinks resolved, 100 MB size limit |
  860. | **Output sandbox** | All generation, write, export, beat sync, subtitle, and reformat handlers enforce `_validate_output_path(anchor_dir=...)` — restricts writes to descendants of the source file's directory, blocking LLM-generated path escapes |
  861. | **Subprocess bounds** | `_ensure_video_asset()` bounds-checks duration (0 < d ≤ 3600s), fps (1–240), width/height (even, ≤ 7680×4320) before `subprocess.run()` — blocks `inf`/`NaN`, negative values, odd dimensions, string injection, and oversized resolutions that could hang or exhaust ffmpeg |
  862. | **Speed validation** | `handle_change_speed` validates speed is positive and ≤100 before any math — prevents ZeroDivisionError crash and nonsensical results |
  863. | **Sandbox roots** | Opt-in and **off by default** — an editor's projects live wherever the user keeps them. `FCP_PROJECTS_DIRS` (several roots, `PATH`-separated) turns on **read** confinement: `_validate_filepath` rejects any path that is neither inside a root as given nor resolves into one. `FCP_PROJECTS_DIR` is unchanged from 0.15.0 — it confines **listing only** and never restricts reads, so an existing install is unaffected by upgrading. Traversal still normalises before the check (`root/../etc` is judged as `/etc`), and the extension whitelist still runs on the *resolved* suffix, so `innocent.fcpxml → /etc/passwd` is rejected either way |
  864. | **Directory listing** | Confined to `FCP_PROJECTS_DIR` when set, plus any `FCP_PROJECTS_DIRS` roots — unchanged behaviour. `find_fcpxml_files` globs `*.fcpxml` / `*.fcpxmld` under the requested directory and every path that is subsequently opened goes back through `_validate_filepath`; with neither variable set, the caller may name any directory to list |
  865. | **Resource caps** | The `list_projects` walk **stops** at `FCP_MAX_DISCOVERY_FILES` (10,000) rather than collecting and slicing, so pointing it at `/` cannot walk the filesystem; marker batches and imports stop at `FCP_MAX_BATCH_MARKERS` (10,000); inline transcript text stops at `FCP_MAX_TRANSCRIPT_CHARS` (1 MB), cut on a line boundary so a timestamp is never split. Every cap returns an explicit `⚠️ TRUNCATED` notice naming what was dropped — a partial result is never presented as a complete one |
  866. | **XML parsing** | `defusedxml` with explicit `forbid_entities/external=True` blocks XXE, billion laughs, entity expansion, remote DTD attacks at all 4 entry points (parser, writer, exporter, rough cut) — minidom pretty-print path also hardened via `defusedxml.minidom`. Ruff `S314`/`S320` rules enforce safe parsing in CI |
  867. | **JSON depth limit** | Iterative BFS depth checker rejects payloads nested beyond 50 levels — immune to RecursionError even at ~1000 nesting |
  868. | **Symlink resolution** | `_validate_filepath` calls `Path.resolve()` *before* the extension whitelist runs, so a symlink named `innocent.fcpxml` that points at `/etc/passwd` is rejected on its resolved suffix — a symlink cannot smuggle a disallowed target past the file gate |
  869. | **Marker strings** | Sanitized via `_sanitize_xml_value()` — null bytes, control chars stripped before write |
  870. | **Role values** | Stripped of control characters before XML attribute assignment |
  871. | **Resource URI parsing** | `file://` and `preview://` URIs have their scheme removed with `str.removeprefix()` (leading match only, so a path containing the scheme string is not mangled) and are then `urllib.parse.unquote()`d before validation — so percent-encoded traversal, percent-encoded null bytes, and ordinary spaces in filenames are all decoded first and then run through the same `_validate_filepath` gate as every other path |
  872. | **Output suffixes** | Path separators and special characters stripped — no traversal via suffix injection |
  873. | **Marker types** | `completed` attribute strict-matched (`'0'`/`'1'` only) — rejects `"true"`, `"1 OR 1=1"`, whitespace-padded values |
  874. 182 security-specific tests across `test_security.py` (`pytest tests/test_security.py --collect-only -q`) covering XXE, path traversal, sandbox root confinement (single and multi-root), resource caps (discovery walk, marker batch, inline transcript), output path anchoring, input validation, subprocess bounds, minidom hardening, JSON depth limits, role sanitization, ffmpeg parameter bounds, symlink resolution, resource-URI decoding, `preview://` rejection paths, symlinked Final Cut library media, and write-handler sandbox enforcement. Ruff `S` (bandit) rules enforced in CI — `S314`/`S320` block unsafe XML parsing, `S105` catches hardcoded passwords, `S108` flags insecure temp paths. Security events (null bytes, sandbox escapes, unhandled exceptions) are logged via Python `logging` for audit trails.
  875. ---
  876. ## Timestamp Parsing — How Import Tools Place Markers
  877. All subtitle and transcript import tools (`import_srt_markers`, `import_transcript_markers`) funnel through a single internal function: **`_parse_timestamp_parts()`** in `server.py`. Understanding it matters when timestamps don't land where you expect.
  878. ### Supported Formats
  879. | Format | Example | Parts | Result |
  880. |--------|---------|-------|--------|
  881. | **Minutes:Seconds** | `1:30` | 2 | 90.0s |
  882. | **H:MM:SS** | `1:05:30` | 3 | 3930.0s |
  883. | **HH:MM:SS.ms** | `00:02:15.500` | 3 | 135.5s |
  884. | **SMPTE** (HH:MM:SS:FF) | `01:00:10:12` | 4 | 3610.5s @ 24fps |
  885. The SMPTE 4-part format converts the frame component to fractional seconds: `frames / frame_rate`. The default rate is **24fps** — pass `frame_rate=` to override for 25fps (PAL) or 30fps (NTSC) projects.
  886. ### The Import Pipeline
  887. ```
  888. SRT / VTT / YouTube chapters / plain transcript
  889. │
  890. ▼
  891. parse_srt() / parse_vtt() / parse_transcript_timestamps()
  892. │ │ │
  893. └────────────────┴──────────────────────┘
  894. │
  895. split on ':'
  896. │
  897. ▼
  898. _parse_timestamp_parts(parts, frame_rate=24.0)
  899. │
  900. ▼
  901. total seconds (float)
  902. │
  903. ▼
  904. marker placed on timeline
  905. ```
  906. ### Edge Cases
  907. - **Unrecognized part counts** (1 part, 5+ parts) return `None` — the marker is silently skipped, not placed incorrectly
  908. - **Zero frame rate** — falls back to base seconds (frames ignored) rather than dividing by zero
  909. - **Milliseconds** — only carried in 3-part format via `float()` on the seconds component (`"15.500"` → `15.5`)
  910. - **Frame rounding** — SMPTE frames are divided exactly (`12/24 = 0.5`), not rounded to the nearest frame boundary. The resulting float is converted to FCPXML's rational `TimeValue` downstream, preserving precision
  911. ### Why This Matters
  912. Before v0.6.20, the 4-part SMPTE parser silently dropped frames — `01:00:10:12` became `3610.0s` instead of `3610.5s`. At 24fps, that's up to **~0.96 seconds** of drift per marker. If you imported a subtitle file with SMPTE timecodes, every marker was slightly off. This was subtle enough to pass QC but visible when scrubbing.
  913. ---
  914. ## Design Principles
  915. | Principle | Implementation |
  916. |-----------|---------------|
  917. | **Rational time, never floats** | All durations are fractions (`600/2400s`) matching FCPXML's native format — zero rounding errors across trim, split, speed |
  918. | **Non-destructive by default** | Modified files get `_modified`, `_chapters` suffixes. Originals are never overwritten |
  919. | **Single source of truth** | `MarkerType` enum owns serialization: `from_string()` for input, `from_xml_element()` for parsing, `xml_attrs` for writing. `INCOMPLETE` is canonical; `TODO` is a backward-compat alias (same object) |
  920. | **Security-first** | 13-layer defense-in-depth on the tool handlers — see [Security](#security) for the full matrix |
  921. | **Dispatch, not conditionals** | `TOOL_HANDLERS` dict maps names → async handlers. No 1000-line if/elif |
  922. ---
  923. ## Documentation
  924. | Guide | What's Inside |
  925. |-------|---------------|
  926. | **[WORKFLOWS.md](docs/WORKFLOWS.md)** | 8 production recipes — QC pipelines, beat-synced assembly, cross-NLE handoffs, documentary A/B roll |
  927. | **[MCP_ECOSYSTEM.md](docs/MCP_ECOSYSTEM.md)** | How this server composes with GitNexus, filesystem, and memory MCP servers |
  928. | **[CHANGELOG.md](CHANGELOG.md)** | Full version history from v0.1.0 to present |
  929. ---
  930. ## Testing
  931. ```bash
  932. uv run --extra dev pytest tests/ -v # or: python3 -m pytest tests/ -v
  933. ruff check . --exclude docs/ # lint — must pass before committing
  934. ```
  935. 2708 tests across 97 suites, measured 2026-11-13 on v0.32.0: 2703 pass and 5 skip locally (`mcp` 1.28.1, ffmpeg 9.0.1, Pillow, Playwright's Chromium); 2636 pass and 3 skip on `mcp` 2.3.0 with the `intelligence` and `scenes` extras, and 2630 pass and 9 skip on ffmpeg 6.1 via `scripts/test-ffmpeg6.sh` (no browser or Pillow in either, so the rendered-label, motion and hero-asset suites skip as modules; CI runs them in their own job); 2679 pass and 29 skip with `FCP_MCP_INDEX=off` (the extra skips there are the tests OF the cache). The other skips are the cases that need ffmpeg, PySceneDetect or Final Cut Pro present. Coverage spans models, parser, writer, FCPXMLWriter generation, server handlers, rough cut generation, speed cutting & pacing curves, marker pipeline, refactored helper functions, regression fixes, security hardening (XXE, entity expansion, path traversal, sandbox boundaries, minidom defense-in-depth, JSON depth limits, input validation, ffmpeg bounds, write-handler sandboxing), connected clips, roles, diff, export, compound clip flattening, audio track generation, templates, effects, `.fcpxmld` bundles with sidecar preservation, bulk media relink, gap-based multicam storylines (mc-clip angle resolution, caption text, connected-clip timeline positions, the media-tools view), real media silence detection, transcript-driven editing, filtergraph compilation, proxy rendering with artifact duration read-back, source-media visual checks, export watch detection, loopback bridge probing, EDL import, autopush, the operation journal and hash-checked undo, the deliver review gate, bulk organize edits, tiered shot search with its never-transcribes / never-downloads guards, the diversity constraint, the grouped tools dispatching to the flat handlers, the labelled proof pictures (timecodes read back off every sheet and every burned frame), the `preview://` page and its traversal/extension/null-byte/symlink rejection paths, the `final-cut-pro` skill, and DTD validation against Apple's official DTDs.
  936. Several of those are **mutation checks** — they exist to prove an instrument can see the failure it is meant to catch, because a check that reads identically on a good and a bad result certifies nothing:
  937. - `test_the_instrument_can_see_a_wrong_duration` renders a one-second timeline and asserts the probe reads something other than two seconds.
  938. - `test_the_waveform_is_actually_drawn` renders the same video against loud and near-silent audio, so the filmstrips are identical by construction and any byte difference must come from the waveform. This one caught a real shipped defect: `showwavespic` draws on a transparent background that flattens to white, so a white trace was invisible while every ordinary check still passed.
  939. - `test_the_edit_still_reports_success_when_the_push_fails` proves an autopush failure never costs you a file that is already on disk.
  940. - `test_a_touched_source_drops_its_rows` re-exports a source and asserts the cache forgets it; with the (mtime, size) check removed the stale rows survive and the test goes red.
  941. - `test_key_goes_in_the_header_and_nowhere_else` — moving the ElevenLabs key into the URL makes it fail.
  942. - `test_version.py` asserts `server.__version__` matches `pyproject.toml`; the two had disagreed since v0.17.0 without anything noticing.
  943. - `test_proofs.py` (v0.32.0) reads every timecode back off the pictures it guards (each sheet cell against the parsed timeline, both lines of each of the 724 burned frames against the clips on screen at that frame, each thumbnail against the ruler drawn under it, each ruler tick to a pixel, the picture-flash at 00:00:20:03, no label within 8 px of a line, every range in-out with its length, each dB label's ink on its tick, cyan only on record time, one red badge per FAIL) and was broken 158 ways in the real code and seen red.
  944. - `test_palette.py`, `test_schema_budget.py`, `test_front_door.py` and `test_pypi_readme.py` (v0.31.0) each plant the failure they guard against: amber back in a surface, one more character in a tool description, the old card's version in the README, a relative image in the built PyPI description.
  945. ---
  946. ## Requirements
  947. - **Python 3.10+** · **Final Cut Pro for Mac 10.4+** (FCPXML 1.8+; the iPad app has no FCPXML path) · **Claude Desktop** or any MCP client
  948. - **Dependencies** (auto-installed): `mcp` (1.21.1+, including 2.x), `defusedxml`
  949. - **ffmpeg** (optional) — needed for silence analysis (`detect_media_silence`, `remove_media_silence`)
  950. - **`[scenes]` extra** (optional) — adds PySceneDetect for `scenes` detection that can see a cut between similar colours; without it the group falls back to ffmpeg's coarser scene filter and says so.
  951. - **`[find]` extra** (optional, Apple Silicon) — adds `mlx-vlm` + `numpy` so `find` can caption shots offline; without it `find` answers from transcript and metadata and says vision is unavailable.
  952. - **`[intelligence]` extra** (optional) — adds librosa for `detect_beats`; everything else works without it. Install via `uvx --from "fcp-mcp-server[intelligence]" fcp-mcp-server` or `pip install "fcp-mcp-server[intelligence]"` (from source: `pip install -e '.[intelligence]'`).
  953. - See [Compatibility](#compatibility) for full version matrix
  954. ---
  955. ## Ecosystem — XML Mode Today, Live Mode Next
  956. This server is the **safe, offline layer** of FCP automation: no patched binaries, no
  957. private APIs, runs on managed Macs, works without Final Cut Pro installed. It composes
  958. with the live-control side of the ecosystem rather than competing with it:
  959. - **[SpliceKit](https://github.com/elliotttate/SpliceKit)** by [@elliotttate](https://github.com/elliotttate)
  960. with [@latenitefilms](https://github.com/latenitefilms) — live in-process control of a
  961. patched FCP copy with its own ~200-tool MCP server. The deep edit engine here and the
  962. live hands there are complementary by design; an optional bridge to SpliceKit's local
  963. JSON-RPC endpoint is on this project's roadmap (see below).
  964. - **[CommandPost](https://commandpost.fcp.cafe)** by [@latenitefilms](https://github.com/latenitefilms) —
  965. nine years of accessibility-layer FCP automation with a built-in WebSocket control
  966. surface; another candidate live backend.
  967. The full ecosystem analysis and the dual-mode architecture plan live in
  968. [docs/CAPABILITY-AUDIT-2026-06.md](docs/CAPABILITY-AUDIT-2026-06.md).
  969. ---
  970. ## Roadmap
  971. - [x] Core FCPXML parsing (reads v1.8–1.14, writes v1.13) — *v0.8.0*
  972. - [x] `.fcpxmld` bundle support with object-tracking/Cinematic sidecar preservation — *v0.8.0*
  973. - [x] Bulk media relink (`relink_media`) — *v0.8.0*
  974. - [x] DTD validation against Apple's official DTDs — *v0.8.0*
  975. - [x] Timeline analysis, markers, EDL/CSV export
  976. - [x] Clip editing (trim, reorder, split, speed, transitions)
  977. - [x] QC tools (flash frames, gaps, duplicates, health scoring)
  978. - [x] Generation (rough cuts, montages, A/B roll, beat sync)
  979. - [x] MCP Prompts + Resources (auto-discovery)
  980. - [x] Subtitle & transcript import as markers
  981. - [x] Multi-track (connected clips, compound clips, roles)
  982. - [x] Timeline diff + social media reformat
  983. - [x] Silence detection & cleanup
  984. - [x] Cross-NLE export (DaVinci Resolve, Premiere Pro, Avid)
  985. - [x] **Live mode v1** — zero-click push-to-FCP via Apple events, AppleScript library inspection — *v0.9.0*
  986. - [ ] Backend Protocol refactor (one operation layer shared by XML and Live)
  987. - [x] **Media intelligence v1** — real silence detection from source audio (`detect_media_silence`) — *v0.10.0*
  988. - [x] **Silence auto-removal** — `remove_media_silence` cuts real silence with ripple — *v0.11.0*
  989. - [x] **Beat detection** — `detect_beats` (librosa) chains into beat markers + snap-to-beats — *v0.12.0*
  990. - [x] **Transcript-based editing** — local Whisper transcription, edit_by_transcript (remove/keep_only), filler-word removal — *v0.13.0*
  991. - [x] **7 grouped tools** — `inspect`/`diagnose`/`edit`/`mark`/`generate`/`transcript`/`deliver` replace the 62 flat tools as the advertised default, cutting the schema footprint 84.7%; `FCP_MCP_LEGACY_TOOLS=1` keeps the 62 available — *v0.14.0*
  992. - [x] **`preview://` HTML timeline render** — see a cut without opening Final Cut Pro — *v0.14.0*
  993. - [x] **`final-cut-pro` Claude Code skill** — workflow order + FCPXML gotchas — *v0.14.0*
  994. - [x] **Daily scheduled CI** — catches upstream dependency breaks within 24h — *v0.14.0*
  995. - [x] **The Loop** — `preview` (see the edit from the source media), `watch` (notice the Cmd-E export), `import_edl_json`, bridge detection, autopush — *v0.17.0*
  996. - [x] **Speed and sight** — SQLite analysis index with per-clip progress, `scenes` shot-boundary detection, `transcript_pack`, opt-in ElevenLabs Scribe diarization — *v0.18.0*
  997. - [x] **The moat and the ledger** — operation journal + `history`/`undo`, review gate on `deliver`, `organize` bulk edits + `organize_auto`, `find` tiered shot search with offline MLX captions, diversity constraint — *v0.19.0*
  998. - [x] **Crossfades and lanes in preview** — transitions compile to ffmpeg `xfade`, connected video lanes composite over the spine — *v0.20.0*
  999. - [x] **Captions look at a 1080p frame** — `find` vision tier caps the frame it sends the VLM, so a 4K library no longer pays 4× the tokens (#21, @jardelapp) — *v0.21.0*
  1000. - [x] **A wheel that starts** — the publish workflow installs the built wheel into a clean venv and runs `initialize` + `tools/list` before a release ships; the MCP registry check reads `isLatest` and is compiled in CI — *v0.21.1–0.22.1*
  1001. - [x] **Gap-based storylines are visible** — `mc-clip` and `caption` connected to a gap spine parse, the multicam angle resolves to its media, and every media tool walks connected clips too (#23, @tomartmedia) — *v0.23.0*
  1002. - [x] **Every tool reads the whole edit** — the reporting tools (EDL, CSV, markers, keywords, pacing, roles) and the preview follow connected clips too, so a gap-based project no longer exports empty — *v0.24.0*
  1003. - [x] **See the cut** — the `view` MCP Apps timeline rendered inline by the host, `gen` generative fill behind a quote-then-confirm money gate, and the `expected_sha256` project guard; the rest of the October idea set is in [`docs/ROADMAP-2026-10.md`](docs/ROADMAP-2026-10.md) — *v0.26.0*
  1004. - [x] **Files Final Cut actually opens** — transition uids checked against Final Cut's own plugin list (`FxPlug:` prefix, seven wipes that matched no plugin, a "fade" that was a colour look), transitions refused when the clips lack handles, DTD-valid rough-cut transitions, assets copied whole, connected clips on the parent's clock and in DTD order (#30-#34, @brannonwinn) — *v0.27.0*
  1005. - [x] **Pushes Final Cut accepts** — `push_to_fcp` sends a copy carrying its library location, bundles included, so Final Cut 12.3 no longer raises a picker that swallows the import (John Palchak) — *v0.27.1*
  1006. - [x] **Gemini Omni replaces Veo 3.1** before Google retired the preview models from the Gemini API — *v0.27.2*
  1007. - [x] **The proxy is exactly as long as the timeline** — every instant of `preview_render` is the timeline's own picture or a named black substitute, transitions drawn on handles like Final Cut (John Palchak) — *v0.28.0*
  1008. - [x] **Every media tool reads the asset clock** — silence, scenes, transcripts and `find` no longer report "nothing found" on timecoded clips — *v0.29.0*
  1009. - [x] **The proxy has sound** — `preview_render` mixes the timeline's audio on the same clock as the picture — *v0.30.0*
  1010. - [x] **Front door** — one palette (true black, one cyan, red only for failure), the GitHub card and PyPI page rebuilt from scripts, current prices with their sources, a schema budget held by a test — *v0.31.0*
  1011. - [x] **Proof you can read** — every preview picture labelled by the server and returned inline: a contact sheet with cut numbers and timecodes, a check with a ruler and named silences, a 720p proxy with burn-in, a before/after strip per cut; `preview://` is the app — *v0.32.0*
  1012. - [x] **Media clock** — every authored asset and clip on its file's own timecode clock (`tmcd`), so an iPhone ProRes or camera clip no longer imports empty; `validate_timeline` checks it; `insert_clip` / `add_connected_clip` bring any file in by `src` (#45) — *v0.33.0*
  1013. - [x] **MXF and broadcast WAV on their own clock, pushes that do not wait on a permission prompt** — checked in Final Cut 12.4: an MXF timecode and a BWF time reference are the file's clock (written at 0s they import empty); `push_to_fcp` falls back to `open` and verifies on disk; one uid per media file so a cut can be pushed again and again into one library — *v0.35.0*
  1014. - [ ] **Read the open timeline back** — an Accessibility-driven `File > Export XML` so the round trip needs no click from you
  1015. - [ ] **Shot embeddings** — tier-3 ranking is lexical over captions until embeddings land
  1016. - [ ] **Live bridges** — SpliceKit / CommandPost are detected since v0.17.0; the adapters that would drive them are not written
  1017. - [ ] Audio sync detection
  1018. - [ ] Premiere Pro native XML support
  1019. ---
  1020. ## Known Issues
  1021. | Issue | Impact | Workaround |
  1022. |-------|--------|------------|
  1023. | **Still images crash FCP** | PNG/JPEG assets referenced directly in FCPXML crash Final Cut Pro on import (`addAssetClip` null pointer). Confirmed across multiple format configurations, dimension matching, and element types. | Convert stills to short MOVs before referencing: `ffmpeg -loop 1 -i image.png -c:v libx264 -t 2 -pix_fmt yuv420p -r 24 output.mov`. This is an FCP limitation, not an FCPXML spec issue. |
  1024. | **An authored timeline imports empty on timecoded media (0.32.0 and earlier)** | `import_edl_json`, `apply_template` and `add_audio` with a `src` wrote every new asset at `start="0s"`, and `insert_clip` / `add_connected_clip` / `add_audio_clip` started a new clip at `0s` whatever its asset's clock. Final Cut puts an asset on its file's timecode track (an iPhone ProRes or camera `.mov`), so the clips asked for media before the file began and Final Cut showed them empty, with no warning (#45). | Fixed in v0.33.0 — upgrade. On an old install, author from media without a timecode track, or set `<asset start>` to the file's timecode and add it to each clip's `start`; 0.33's `validate_timeline` names the value per file. |
  1025. | **A multicam edit reads as an empty project (0.22.1 and earlier)** | FCP exports connected-clip multicam edits as a spine of gaps with `mc-clip`/`caption` in lanes; the parser dropped both, so `list_clips` was empty, `validate_timeline` scored 100 % and the media tools opened nothing. | Fixed in v0.23.0 — upgrade. On an old install, `list_connected_clips` still shows nothing for these; there is no in-version workaround. |
  1026. | **"Connection closed" on a PyPI install of 0.19.2–0.21.0** | `tools/` was missing from the published package, so the server raised `ModuleNotFoundError` at import, before it could answer `initialize`. The MCP client reports only "Connection closed". A git checkout never showed it. | Fixed in v0.21.1 — upgrade (`uvx` picks it up on the next run; `pip install -U fcp-mcp-server` otherwise). The publish workflow now installs the built wheel into a clean venv and runs `initialize` + `tools/list` before anything ships. |
  1027. <details>
  1028. <summary><strong>Fixed in earlier releases</strong> — kept because the symptom still turns up on old installs</summary>
  1029. | Issue | Impact | Workaround |
  1030. |-------|--------|------------|
  1031. | **Non-standard timebases** | FCP rejects time values with denominators outside its standard set (e.g. `100800/57600s`). Cross-denominator arithmetic previously produced these. | Fixed in v0.5.29 — TimeValue arithmetic now uses LCM, and speed changes snap to frame boundaries in 2400-tick timebase. |
  1032. | **Malformed frameDuration crash** | A `frameDuration` with zero or negative denominator (e.g. `"0/0s"`) in the writer's `_detect_fps` would silently produce 0.0 fps, causing downstream ZeroDivisionError in speed/trim operations. The parser already validated this correctly. | Fixed in v0.6.23 — writer now validates both numerator and denominator, falling back to 30.0 fps. |
  1033. | **Duplicate clip names corrupt edits** | When multiple spine clips share the same name (e.g. `Interview_A` ×4), operations using the name-indexed dict silently target the wrong clip (last-indexed instead of first). Affected: `delete_clip`, `add_marker_at_timeline`, `trim_clip`, `change_speed`, `split_clip`, `add_transition`, `reorder_clips`. | Fixed in v0.6.37–0.6.39 — all methods now resolve clips via `_resolve_clip()` which walks the spine directly, returning the first match. |
  1034. </details>
  1035. ---
  1036. ## Reporting a Problem
  1037. You do not need a GitHub account, and you do not need to be a programmer.
  1038. - **GitHub:** [open an issue](https://github.com/DareDev256/fcp-mcp-server/issues) — best for anything with a traceback or a sample FCPXML.
  1039. - **Email:** [dev@jamesdare.com](mailto:dev@jamesdare.com) — read directly, answered directly. If Claude did the diagnosis for you, paste its findings as-is; that is exactly how the v0.21.1 packaging bug was reported and it was correct in every particular.
  1040. **If the client only says "Connection closed"**, the server died before it could answer. Run it by hand to see the real error:
  1041. ```bash
  1042. uvx fcp-mcp-server # or: python server.py from a checkout
  1043. ```
  1044. A Python traceback here (import error, missing dependency) is the whole story; send that.
  1045. Want to try builds before they ship? Say so in the email — pre-release wheels go out to a small list of working editors.
  1046. ## Status & Contributing
  1047. **Actively maintained** — live-verified against FCP 12.2, with external contributions already merged and credited: [@mikegrant25](https://github.com/mikegrant25) (sandbox security fix, #6), [@jardelapp](https://github.com/jardelapp) (audio duration probing, #7), and Marty Hou, documentary editor, who reported the v0.19.2–0.21.0 packaging failure by email. The diagnosis he forwarded was produced with Claude on his own machine, checked against the published artifacts rather than from memory, and held on every point — his words, recorded here the way he asked for them.
  1048. PRs welcome. If you're a video editor who codes (or a coder who edits), let's build this together.
  1049. ## Credits
  1050. Built by [@DareDev256](https://github.com/DareDev256) — former music video director, now building AI tools for creators.
  1051. ## More from the same author
  1052. - **[frameio-to-final-cut-pro](https://github.com/DareDev256/frameio-to-final-cut-pro) (Cut Review):** Frame.io comments and client notes go into Final Cut Pro as to-do markers on the right clips, then one page shows which notes the recut touched. Built on this server's parser, free, no upload: `uvx cutreview`.
  1053. - **[Ultimate Image & Video Prompt Generator](https://github.com/DareDev256/Ultimate-Image-Video-Prompt-Generator):** a prompt workbench for nine image and video engines, every suggestion credited to the creator it came from. [Live](https://prompts.tdotssolutionsz.com).
  1054. - **[clickfix-protection-macos](https://github.com/DareDev256/clickfix-protection-macos):** defensive tools for macOS against paste-this-command (ClickFix) attacks, written after one came at me.
  1055. - **[jackpoint](https://github.com/DareDev256/jackpoint):** one command installs Claude Code, Gemini CLI, Codex CLI and other AI coding tools on a Mac, for people who have never used a terminal.
  1056. Everything else is on [my GitHub profile](https://github.com/DareDev256).
  1057. ## License
  1058. MIT — see [LICENSE](LICENSE).
  1059. <!-- MCP registry ownership marker -->
  1060. `mcp-name: io.github.DareDev256/fcpxml-mcp-server`

Version history

  • v0.35.011/17/2026

  • v0.34.111/16/2026

  • v0.33.011/15/2026

  • v0.32.011/14/2026

  • v0.30.011/5/2026

  • v0.27.210/23/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.