<p align="center">
  <img src="assets/banner.png" alt="fcp-mcp: let Claude analyze, edit and QC your Final Cut Pro timelines" width="100%">
</p>

<p align="center">
  <b>English</b> · <a href="README.ko.md"><b>한국어</b></a>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/github/license/kks0488/fcp-mcp?color=a78bfa" alt="MIT license"></a>
  <img src="https://img.shields.io/badge/TypeScript-5.x-3178c6?logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/MCP-server-8b5cf6" alt="MCP server">
  <img src="https://img.shields.io/badge/macOS-Final%20Cut%20Pro%2010.6%2B-111?logo=apple&logoColor=white" alt="macOS, Final Cut Pro 10.6+">
  <img src="https://img.shields.io/badge/tests-91%20passing-22c55e" alt="91 tests passing">
  <a href="https://github.com/kks0488/fcp-mcp/stargazers"><img src="https://img.shields.io/github/stars/kks0488/fcp-mcp?style=flat&color=f472b6" alt="GitHub stars"></a>
  <img src="https://img.shields.io/github/last-commit/kks0488/fcp-mcp?color=64748b" alt="Last commit">
</p>

<h2 align="center">Talk to your Final Cut Pro timeline.<br>Claude reads it, edits it and checks it before you export.</h2>

<p align="center">
  An MCP server with 30 tools that parse, edit, quality-check and generate FCPXML,<br>
  plus AppleScript and GUI automation to move timelines in and out of Final Cut Pro without menu clicks.
</p>

<table>
<tr>
<td width="50%" valign="top">

### 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.

</td>
<td width="50%" valign="top">

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

</td>
</tr>
<tr>
<td width="50%" valign="top">

### 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.

</td>
<td width="50%" valign="top">

### 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.

</td>
</tr>
</table>

<p align="center">
  <img src="assets/demo.png" alt="Claude Code calling fcp-mcp: timeline analysis, pacing histogram and a QC health score" width="88%">
</p>
<p align="center"><sub>Real output of <code>fcp_analyze_timeline</code>, <code>fcp_analyze_pacing</code> and <code>fcp_validate_timeline</code> on the bundled sample timeline.</sub></p>

## Quick start

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

```bash
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

```bash
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`:

```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"*.

## 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)

| Tool | Description |
|------|-------------|
| `fcp_list_projects` | Scan a directory for `.fcpxml` / `.fcpxmld` files |
| `fcp_analyze_timeline` | Resolution, FPS, duration, clip count, markers |
| `fcp_list_clips` | All clips with timecodes, media paths, keywords |
| `fcp_analyze_pacing` | Cuts-per-minute with histogram visualization |

### Markers & Keywords (4)

| Tool | Description |
|------|-------------|
| `fcp_list_markers` | List markers filtered by type (standard/chapter/todo) |
| `fcp_add_marker` | Add a marker at SMPTE timecode or rational time |
| `fcp_batch_add_markers` | Add multiple markers in one operation |
| `fcp_list_keywords` | List keyword ranges applied to clips |

### Editing (6)

| Tool | Description |
|------|-------------|
| `fcp_trim_clip` | Change clip in-point and/or duration |
| `fcp_reorder_clips` | Move a clip to a different position in timeline |
| `fcp_delete_clips` | Remove clips by index |
| `fcp_split_clip` | Split a clip at a timecode |
| `fcp_change_speed` | Apply speed changes (slow-mo, fast-forward) |
| `fcp_add_transition` | Add cross-dissolve transitions between clips |

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

### Quality Control (4)

| Tool | Description |
|------|-------------|
| `fcp_detect_gaps` | Find gaps (black frames) in the timeline |
| `fcp_detect_flash_frames` | Detect clips shorter than threshold |
| `fcp_detect_duplicates` | Find clips reusing the same source media |
| `fcp_validate_timeline` | Full health check with score (A-F grade) |

### Generation (2)

| Tool | Description |
|------|-------------|
| `fcp_generate_rough_cut` | Generate a rough cut with pacing control |
| `fcp_generate_montage` | Generate a montage with accelerating/decelerating pacing curves |

### Export (2)

| Tool | Description |
|------|-------------|
| `fcp_export_edl` | Export as CMX 3600 EDL |
| `fcp_export_csv` | Export clip data as CSV spreadsheet |

### FCP Live Control — AppleScript (6)

Requires Final Cut Pro to be running.

| Tool | Description |
|------|-------------|
| `fcp_app_status` | Check if FCP is running, get version |
| `fcp_list_libraries` | List all open libraries |
| `fcp_list_events` | List events in a library |
| `fcp_list_projects_live` | List projects via AppleScript |
| `fcp_get_project_info_live` | Get project details by name |
| `fcp_import_xml` | Import FCPXML via `open -a` command |

### 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).

| Tool | Description |
|------|-------------|
| `fcp_export_xml_gui` | Automate File > Export XML with path navigation |
| `fcp_import_xml_gui` | Import FCPXML and handle library selection dialog |

## 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:
```bash
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

```bash
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`](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](LICENSE). Final Cut Pro is a trademark of Apple Inc.; this project is not affiliated with Apple.