fcp-mcp

Understand any timeline

Resolution, frame rate, clips, gaps, markers and keywords in one call. Pacing analysis shows cuts per minute and a clip-length histogram.

Edit without risk

Trim, split, reorder, delete, change speed and add transitions. Every edit writes a new *_modified.fcpxml; the original is never touched.

QC before export

Detect gaps (black frames), flash frames and reused media, then get a health score (A–F). Output is validated against Apple's FCPXML v1.14 DTD.

Hands-free roundtrip

Export XML from Final Cut Pro, let the AI edit, validate, and import it back. System Events drives the File menu so no manual steps are needed.

Quick start

Requirements: macOS, Node.js 18+, Final Cut Pro 10.6+ (for live control, GUI automation and DTD validation).

git clone https://github.com/kks0488/fcp-mcp.git
cd fcp-mcp
npm install
npm run build
npm test        # 91 tests

Connect to Claude Code

claude mcp add fcp-mcp -- node /path/to/fcp-mcp/dist/index.js

Connect to Claude Desktop

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

{
  "mcpServers": {
    "fcp-mcp": {
      "command": "node",
      "args": ["/path/to/fcp-mcp/dist/index.js"]
    }
  }
}

Then ask things like "Analyze ~/Movies/Edit.fcpxml", "Add chapter markers every 30 seconds" or "Find flash frames and gaps before I export".

Related MCP server: fcp-mcp-server

How the roundtrip works

1. EXPORT    fcp_export_xml_gui      File > Export XML, driven by System Events
2. AI EDIT   fcp_add_marker, fcp_trim_clip, ...   parse → modify → write *_modified.fcpxml
3. VALIDATE  xmllint --dtdvalid       FCPXML v1.14 DTD compliance
4. IMPORT    fcp_import_xml_gui      open in Final Cut Pro and pick the library

Without GUI automation, steps 1 and 4 are a manual File menu action. FCP's AppleScript dictionary is read-only, which is why the GUI layer exists.

Tools (30)

Analysis (4)

Markers & Keywords (4)

Editing (6)

All edit tools write to *_modified.fcpxml — originals are never touched.

Quality Control (4)

Generation (2)

Export (2)

FCP Live Control — AppleScript (6)

Requires Final Cut Pro to be running.

FCP GUI Automation — System Events (2)

Requires Accessibility permissions. Automates FCP menu interactions that are impossible via AppleScript (FCP's scripting API is read-only).

Architecture

src/
├── index.ts                    MCP server entry point (stdio transport)
├── engine/
│   ├── models.ts               1,055 lines — Full FCPXML v1.14 type system
│   ├── fcpxml-parser.ts        1,443 lines — XML → TypeScript parser
│   ├── fcpxml-writer.ts          939 lines — TypeScript → FCPXML writer
│   ├── fcpxml-validator.ts       146 lines — DTD validation via xmllint
│   └── time.ts                   245 lines — Rational time & SMPTE arithmetic
└── tools/
    ├── shared.ts                  24 lines — ToolDefinition, ok(), err()
    ├── analyze.ts                423 lines — Timeline analysis
    ├── markers.ts                515 lines — Marker CRUD
    ├── edit.ts                   748 lines — Clip editing
    ├── qc.ts                     579 lines — Quality control
    ├── generate.ts               498 lines — Timeline generation
    ├── export.ts                 261 lines — EDL/CSV export
    ├── fcp-control.ts            499 lines — AppleScript bridge
    └── fcp-gui.ts                383 lines — System Events GUI automation

Data Flow

                          ┌─────────────┐
Claude/AI ──MCP stdio──▶  │  fcp-mcp    │
                          │  server     │
                          └──────┬──────┘
                     ┌───────────┼───────────┐
                     ▼           ▼           ▼
               ┌──────────┐ ┌──────────┐ ┌──────────────┐
               │  Engine   │ │  Engine   │ │  System      │
               │  Parser   │ │  Writer   │ │  Events      │
               └────┬─────┘ └────┬─────┘ └──────┬───────┘
                    ▼            ▼               ▼
               .fcpxml       .fcpxml       Final Cut Pro
               (read)        (write)       (GUI control)

• FCPXML tools (analyze, edit, QC, generate, export, markers) read/write .fcpxml files directly — FCP does not need to be running

• Live control tools query FCP via AppleScript — FCP must be running

• GUI automation tools control FCP menus via System Events — FCP must be running + Accessibility permissions

FCPXML Format

This server works with FCPXML v1.14, Apple's XML interchange format for Final Cut Pro. Key concepts:

• .fcpxml — Single XML file containing timeline data

• .fcpxmld — Bundle (directory) containing Info.fcpxml inside

• Resources — Assets (media files), formats (resolution/fps), effects

• Spine — The primary storyline containing clips in sequence

• Rational Time — Time as fractions (e.g., 3600/2400s = 1.5 seconds at 24fps)

The server handles both .fcpxml and .fcpxmld transparently.

Permissions Setup (GUI Automation)

For fcp_export_xml_gui and fcp_import_xml_gui to work:

1. Open System Preferences > Privacy & Security > Accessibility

2. Add your terminal app (Terminal.app, iTerm2, etc.)

3. If using through Claude Code/Desktop, also add the app running the MCP server

Verify with:

osascript -e '
tell application "System Events"
    tell process "Final Cut Pro"
        return name of every menu of menu bar 1
    end tell
end tell'

Expected output: the list of Final Cut Pro menu names (localized to your macOS language).

Development

npm test              # vitest
npm run dev           # start the server with tsx
npm run build         # compile to dist/
npx tsc --noEmit      # type check only

DTD validation uses the FCPXMLv1_14.dtd that ships inside Final Cut Pro (see dtd/README.md). On a machine without Final Cut Pro, validator tests fail unless you place the DTD in dtd/.

FAQ

Does Final Cut Pro need to be running? Only for the live-control and GUI tools. Analysis, editing, QC, generation and export work on .fcpxml / .fcpxmld files directly.

Will it overwrite my project? No. Edit tools always write *_modified.fcpxml next to the original.

Which FCPXML version? v1.14. Both single files and .fcpxmld bundles are supported.

License

MIT © Kyoungsoo Kim — see LICENSE. Final Cut Pro is a trademark of Apple Inc.; this project is not affiliated with Apple.