fcp-mcp — Final Cut Pro MCP Server

Trusted, local, human-approved Final Cut Pro workflows. fcp-mcp inspects, generates, and transactionally edits FCPXML, then optionally hands verified artifacts to Final Cut Pro. The default profile never performs direct live or offline mutation.

Version 0.3.0 freezes a 94-tool catalog across four profiles. It is a bounded FCPXML interchange and tested Final Cut Pro handoff surface—not a claim of complete autonomous Final Cut Pro control. The default workflow is inspect, prepare, review, hash approval, then commit.

You: "Find and repair flash frames in hero.fcpxml."
Claude → fcpxml_detect_flash_frames → fcpxml_workflow_prepare
       → review semantic diff + candidate hash → fcpxml_workflow_commit
Result: the reviewed candidate is atomically committed with durable evidence

Start here:

• Documentation index
• First run
• Compatibility
• Support
• Security
• v0.3.0 release and fresh product evidence
• Agent operating guide
• Production workflow recipes
• v0.3 changelog
• v0.3.0 review evidence

Project Structure

fcp-mcp/
├── src/fcp_mcp/
│   ├── __init__.py
│   ├── __main__.py              # python -m fcp_mcp CLI
│   ├── cli.py                   # serve, doctor, doctor --json, --version
│   ├── config.py                # immutable environment configuration
│   ├── contracts.py             # stable errors + structured diagnostics
│   ├── diagnostics.py           # non-mutating runtime readiness checks
│   ├── observability.py         # text/JSON transaction events
│   ├── server.py                # MCP v2 entry and profile-selected handlers
│   ├── tool_metadata.py         # MCP safety annotation presets
│   ├── automation/
│   │   └── osascript.py         # argv-isolated AppleScript/JXA runner
│   ├── security/
│   │   └── paths.py             # allowed-root and output policy
│   ├── fcpxml/
│   │   ├── parser.py            # FCPXML → Python object tree
│   │   ├── writer.py            # transactional XML mutation/writing
│   │   ├── models.py            # TimeValue, Timecode, Clip, Timeline, etc.
│   │   ├── time_utils.py        # rational-arithmetic timecode
│   │   ├── analysis.py          # pacing, flash frames, gaps, duplicates
│   │   ├── validator.py         # DTD-style structural validation
│   │   ├── generator.py         # programmatic project/timeline creation
│   │   ├── puppet.py            # character puppet system
│   │   ├── diff.py              # timeline A/B comparison
│   │   └── transaction.py       # validated atomic FCPXML commits
│   ├── fcp_control/             # AppleScript bridge for live FCP control
│   ├── media/
│   │   └── ffprobe.py           # ffprobe wrapper for media analysis
│   ├── pipeline/                # multi-step workflows
│   ├── workflow/                # durable prepare, approval, commit, recovery
│   └── utils/
│       ├── atomic_write.py       # backup, replace, rollback
│       ├── safe_xml.py          # defusedxml hardening
│       └── paths.py             # trusted system path helpers
├── tests/                       # complete unit + contract suite
├── scripts/                     # docs, coverage, and wheel gates
├── docs/
│   ├── README.md                # documentation map and status
│   ├── research/                # dated research records
│   └── reviews/                 # release evidence and decisions
├── examples/
│   ├── quickstart.py            # install verification
│   └── GALLERY.md               # workflow gallery with prompts
├── pyproject.toml
├── server.json                  # MCP Registry manifest
├── LLM_GUIDE.md                 # operational guide for agents
├── WORKFLOWS.md                 # production recipes
├── CHANGELOG.md
├── ROADMAP.md
├── CONTRIBUTING.md
└── LICENSE

Setup

Prerequisites

• Python 3.10+
• macOS 15.6 or later with Final Cut Pro
• FFmpeg on $PATH (for media_* tools): brew install ffmpeg
• Apple Compressor (optional, for compressor_* tools)

Install

Install the current published release from PyPI:

pipx install fcp-mcp

Or from source (for contributors):

git clone https://github.com/dreliq9/fcp-mcp.git
cd fcp-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Verify

fcp-mcp --version
fcp-mcp doctor
fcp-mcp doctor --json
python examples/quickstart.py

doctor exits 0 when ready, 1 when offline service is usable but optional capabilities are degraded, and 2 when configuration blocks required runtime behavior. MCP clients can call the same structured surface through fcp_doctor.

Connect to Claude Code

claude mcp add-json fcp '{"type":"stdio","command":"fcp-mcp"}' --scope user

Or if you installed from source, point at your venv's Python:

claude mcp add-json fcp '{"type":"stdio","command":"/FULL/PATH/TO/.venv/bin/fcp-mcp"}' --scope user

Or edit ~/.claude.json directly:

{
  "mcpServers": {
    "fcp": {
      "type": "stdio",
      "command": "fcp-mcp"
    }
  }
}

Claude Desktop

Add the same config to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Verify connection

claude mcp list       # from terminal
/mcp                  # inside Claude Code

Catalog Profiles

Select a profile with FCP_MCP_PROFILE. The default workflow profile keeps the inspect → prepare → review → hash approval → commit sequence bounded and reviewable.

The 94 tools include the youtube-mcp.materialized-clip-plan/v1 provenance adapter, fcpxml_generate_from_clip_plan, in edit and full only. Live FCP control remains independently disabled unless FCP_MCP_ENABLE_LIVE_CONTROL=1; choosing full does not grant that authority.

Available Tools (94 in full)

The full catalog combines 93 domain tools across 13 functional categories with fcp_doctor.

Key Features

Three layers in one server

Most FCP MCPs pick a lane. DareDev256/fcpxml-mcp-server is FCPXML-only. elliotttate/finalcutpro-mcp is AppleScript/JXA-heavy with thin FCPXML. fcp-mcp does both — and adds media analysis (ffprobe) and a parametric puppet system on top. An agent can open a library, inspect the active timeline, patch the XML, re-import, trigger Share, and dispatch a Compressor job — end to end.

Rational-arithmetic timecode

Time values are stored as fractions ("720/24s") and only collapsed to floats at display boundaries. Frame-accurate across 23.976 / 24 / 29.97 / 59.94 / drop-frame — no rounding drift when splitting, trimming, or concatenating.

Scoped and transactional XML handling

All .fcpxml reads go through defusedxml via utils/safe_xml.py — XXE, entity expansion, and external entities are blocked by default. The parser enforces configured XML size and depth limits.

User paths are resolved beneath configured roots after symlink resolution. FCPXML writes are serialized to a secure temporary file beside the destination, structurally validated, backed up when replacing an existing destination, atomically committed, and validated again. The built-in validator checks the invariants it implements; it is not a complete Apple schema validator. Import into a disposable Final Cut Pro project is the authoritative compatibility gate for important outputs. On a release workstation with Final Cut Pro installed, preflight a candidate against the DTD matching its declared FCPXML version:

python scripts/apple_dtd_gate.py path/to/candidate.fcpxml

This gate reads the DTD from the installed Final Cut Pro application bundle; the project does not copy or redistribute Apple's schema. A passing DTD check does not replace the disposable-project import because Final Cut Pro also checks media and application-level semantics.