fcp-mcp — Final Cut Pro MCP Server

fcp-mcp — Final Cut Pro MCP 服务

可信、本地且经人工批准的 Final Cut Pro 工作流。 fcp-mcp 可检查、生成并以事务方式编辑 FCPXML，然后可选择将经验证的成品交给 Final Cut Pro。默认配置不会直接修改实时或离线项目。

此开发目录在 v0.3.0 基线上，为四种配置新增了三个导入桥接工具。这是一个范围有限的 FCPXML 互操作和经过测试的 Final Cut Pro 交接界面，并不代表能够完全自主地控制 Final Cut Pro。默认工作流是检查、准备、审查、哈希批准，然后提交。

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

从这里开始：

• 文档索引
• 首次运行
• 兼容性
• 支持
• 安全
• v0.3.0 发布和最新产品证据
• Agent 操作指南
• 生产工作流配方
• v0.3 更新日志
• v0.3.0 审查证据

项目结构

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

---

设置

前提条件

• Python 3.10+
• macOS 15.6 或更高版本，并安装 Final Cut Pro
• FFmpeg 位于 $PATH 中（用于 media_* 工具）：brew install ffmpeg
• Apple Compressor（可选，用于 compressor_* 工具）

安装

从 PyPI 安装当前已发布版本：

pipx install fcp-mcp

或从源代码安装（适用于贡献者）：

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

验证

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

准备就绪时，doctor 会以 0 退出；离线服务可用但可选功能受限时，以 1 退出；配置妨碍必需运行时行为时，以 2 退出。MCP 客户端可通过 fcp_doctor 调用相同的结构化接口。

连接到 Claude Code

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

或者，如果你从源代码安装，请指定虚拟环境中的 Python：

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

或者直接编辑 ~/.claude.json：

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

Claude Desktop

将相同配置添加到 Claude Desktop 配置文件中：

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

验证连接

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

---

目录配置

使用 FCP_MCP_PROFILE 选择配置。默认的 workflow 配置会将检查 → 准备 → 审查 → 哈希批准 → 提交的流程限制在明确范围内，并支持审查。

配置	工具	提示词	资源	用途
inspect	30	2	0	离线检查和诊断
workflow（默认）	34	3	3	可审查的事务式 FCPXML 编辑
edit	76	5	3	直接离线修改、导入准备和工作流
full	97	5	3	所有离线工具，以及选择启用的实时 FCP、媒体和 Compressor 工具

97 个工具中包含 youtube-mcp.materialized-clip-plan/v1 溯源适配器 fcpxml_generate_from_clip_plan，但仅适用于 edit 和 full 配置。除非设置 FCP_MCP_ENABLE_LIVE_CONTROL=1，否则实时 FCP 控制仍会单独保持禁用；选择 full 并不会授予该权限。

可用工具（full 中共 97 个）

完整目录包含 14 个功能类别中的 96 个领域工具，以及 fcp_doctor。

类别	数量	功能
inspect	8	解析、列出片段／标记／效果／角色，分析节奏、时间线统计信息及 A/B 差异
qc	10	检查闪帧、间隙、重复项、媒体链接、帧率、音频电平、安全区域、时长、结构有效性，并生成汇总 QC 报告
edit	12	管理标记、关键词、标题、音频、转场、修剪、拆分、删除、重排、速度、角色分配和重新排版
heal	3	修复闪帧、填补间隙、移除静音
batch	4	管理标记、重命名、分配角色，以及为多个片段应用转场
generate	5	新建项目／时间线、粗剪、蒙太奇，以及保留来源信息的片段计划 FCPXML
templates	3	列出并保存 FCPXML 模板；fcpxml_apply_template 在 v0.3.0 中仍为 unsupported_contract
io	5	导入 SRT／EDL，导出 EDL、DaVinci Resolve XML 和 Premiere FCP7 XMEML
live	20	基于 AppleScript 操作资料库／事件／项目、播放、菜单／键盘、共享和发现
import bridge	3	准备经过验证且绑定目标的 XML、发送一个获批的原生请求，并协调元数据
puppet	7	在 FCPXML 中创建参数化角色绑定，并使用动作预设
media	10	使用 ffprobe 和 ffmpeg 获取信息、响度、静音、节拍、场景、缩略图及音频转 MIDI
compressor	2	列出 Compressor 设置并分派编码任务
workflow	4	准备、检查、通过哈希批准、提交或取消持久化编辑运行

主要功能

一个服务中的三个层次

大多数 FCP MCP 工具只专注于一个方面。DareDev256/fcpxml-mcp-server 仅支持 FCPXML。 elliotttate/finalcutpro-mcp 主要依赖 AppleScript/JXA，FCPXML 支持较浅。 fcp-mcp 两者兼备，并在此基础上加入媒体分析（ffprobe）和参数化木偶系统。Agent 可以打开资料库、检查当前时间线、修补 XML、重新导入、触发共享，并分派 Compressor 任务——实现端到端操作。

有理数运算时间码

时间值以分数形式存储（"720/24s"），仅在显示时转换为浮点数。可在 23.976／24／29.97／59.94／丢帧模式下实现帧精确，拆分、修剪或拼接时不会产生舍入漂移。

作用域受限且具事务性的 XML 处理

所有 .fcpxml 文件的读取都通过 utils/safe_xml.py 中的 defusedxml 完成，默认阻止 XXE、实体扩展和外部实体。 解析器会强制执行配置的 XML 大小和深度限制。

在解析符号链接后，用户路径会被解析到配置的根目录之下。写入 FCPXML 时，会先序列化到目标文件旁的安全临时文件，进行结构验证；替换现有目标时会先备份，然后原子提交并再次验证。内置验证器会检查其实现的各项不变量，但并非完整的 Apple 架构验证器。对于重要输出，导入到一次性 Final Cut Pro 项目中才是权威的兼容性检查。在安装了 Final Cut Pro 的发布工作站上，请根据候选文件声明的 FCPXML 版本，使用对应的 DTD 进行预检：

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

此检查会从已安装的 Final Cut Pro 应用程序包中读取 DTD；项目不会复制或重新分发 Apple 的架构文件。通过 DTD 检查并不能取代一次性项目导入，因为 Final Cut Pro 还会检查媒体和应用程序层面的语义。

fcpxml_assign_role、fcpxml_batch_assign_roles 及其工作流操作会分配音频角色。对于 asset-clip，fcp-mcp 会写入 Apple 的 audioRole 属性，并继续读取旧版 role 值以保持兼容。

可审查的事务性编辑

默认配置文件提供四个工作流工具： fcpxml_workflow_prepare、fcpxml_workflow_status、 fcpxml_workflow_commit 和 fcpxml_workflow_cancel。

Prepare 会运行一个固定且有界的编辑图，并将候选文件、语义差异、 验证证据和事件链存储在私有目录 FCP_MCP_STATE_DIR 下。它不会创建或更改公开目标位置。 请检查返回的摘要和 diff_uri，然后将准确返回的 candidate_sha256 作为 expected_candidate_sha256 传给 commit。 客户端批准会以加密方式绑定到该候选文件，但记录为 client_unverified_human；服务器无法独立证明是人类批准了聊天消息。

三个只读模板提供持久证据： fcp-workflow://runs/{run_id}、 fcp-workflow://runs/{run_id}/events 和 fcp-workflow://runs/{run_id}/diff。候选 XML 有意保持私有， 不会作为资源公开。中断的 commit 会根据持久证据进行评估，并可通过以下命令显式协调：

fcp-mcp workflow reconcile RUN_ID --json

这是一个有界工作流引擎，而不是通用图运行时。它不使用 MCP Tasks，也不会运行后台自主 Agent。

跨 NLE 导出

将同一时间线导出为三个目标格式：

• fcpxml_export_resolve — DaVinci Resolve 风格的 XML（v1.9）
• fcpxml_export_fcp7 — 兼容 Premiere 的 XMEML（FCP7 格式）
• fcpxml_export_edl — 用于调色和归档工作流的纯 EDL

参数化角色木偶

puppet_* 工具完全使用 FCPXML 构建动画角色绑定 — 无需第三方动画模板。部件、关键帧和预设（行走、说话、挥手、多角色构图）会生成 XML， 以供结构验证，随后通过一次临时项目的 FCP 导入关卡。

剪辑前进行 QC

fcpxml_qc_report("hero.fcpxml")
  → Markdown validation summary and timeline statistics
  → gaps and flash frames with timecodes
  → duplicate sources
  → pacing distribution

媒体链接、帧率、音频电平、安全区域和目标时长分别由不同的 fcpxml_check_* 工具检查。请运行所需的具体检查，不要假设汇总报告包含这些检查。

程序化 XML 导入桥接

fcpxml_prepare_import(path, library_path) 会准备一个指定的事件/项目，不会联系 Final Cut。它要求存在 .fcpbundle、范围受限的本地媒体文件，以及匹配的已安装 Apple DTD。其私有工件包含 Apple 文档中说明的 import-options 资源库 URL。媒体会复制到私有快照中，并受 FCP_MCP_WORKFLOW_MAX_ARTIFACT_BYTES 限制（暂存媒体与暂存 XML 的总大小；默认每次准备为 268,435,456 字节 / 256 MiB），随后会要求 Final Cut 将资源复制到其资源库。警告仍会显示。存在冲突的嵌入目标会被拒绝。支持出厂 Motion 模板 UID 和匹配的已安装出厂定位器；外部 Motion 模板和定位器资源会被拒绝。媒体书签会被移除，并改用经过审查的快照 URL。

分发会使用经过审查 XML 的独立密封副本，其中固定了每个暂存文件的身份和哈希值。桥接程序会在原生预检后检查这些信息。文件权限为 0400，快照目录权限为 0500；公开路径工具无法访问保留的暂存树。快照会保留以供异步读取，包括元数据观察之后；不会自动清理。这会占用磁盘空间。请在请求、协调及证据/恢复决策期间，将整个私有导入状态（包括快照、计划和分发记录）保留在 FCP_MCP_STATE_DIR/import-bridge 下。分发前请勿更改源 XML。请勿删除、移动已准备的快照，也不要更改其权限。收到接受结果或匹配的元数据，并不能证明 Final Cut 已完成读取。删除状态也会移除重复分发证据；证据缺失并不授权再次导入。 请为保留的工作使用稳定且私有的 FCP_MCP_STATE_DIR。受管工作区可能会规范化目录权限，从而使 0500 封印失效。对于有时限的测试，临时位置（例如 /private/tmp）可以避免这种规范化，但操作系统或其他进程可能会删除其中的内容；这些位置不能保证持久保留。如果状态、权限或身份发生变化，请停止并调查；不要修复权限或绕过验证来强行发送。此桥接不提供清理或状态迁移行为。

这些控制以可信的操作系统账户和已安装的 Final Cut 应用为前提。它们无法隔离同一用户或 root 运行的恶意进程；此类进程可能会在应用读取路径前更改权限或替换路径。这三个桥接工具会拒绝未知参数，并要求严格的架构类型。

批准返回的 plan_sha256 前，请检查该产物和目标。 使用 full 配置文件、启用实时控制并采用客户端审批模式时， fcp_request_import(prepared_id, expected_plan_sha256) 会检查当前打开的库，阻止使用已有事件名称，记录意图，并发送一次 Open Document AppleEvent。accepted_unverified 表示事件返回时没有错误； 这并不表示导入已完成。预检与原生处理并非原子操作，因此应用状态可能会变化，Final Cut 仍可能弹出提示。如果目标在处理前消失，Apple 可能会创建一个库。原生错误／超时的结果仍不明确，已记录的请求绝不会自动重发。尚未解决的请求也会阻止向该库发起其他请求。

fcp_reconcile_import(prepared_id) 会读取应用元数据并更新私有记录。metadata_observed 仅确认预期的库 URL、事件／项目身份和时长。它不会验证时间线内容或渲染结果。若观察结果缺失、不匹配或不可用，请等待或手动检查，不要再次导入。CLI 审批模式会阻止桥接分发；它不会被静默替换为客户端审批。XML 导出和渲染仍取决于 Final Cut。较早的 fcp_import_xml 工具保持不变。

Apple 规范：程序化导入 和导入选项。

实时 FCP 控制

FCP 正在运行时，fcp_* 工具会通过 AppleScript 连接：

fcp_open_library(...)
fcp_get_timeline_info()    → current project, active range, playhead
fcp_playback("play" | "pause" | "goto" | "in_out")
fcp_menu_command("File > Export > Export Using Compressor Settings...")
fcp_keyboard_shortcut("cmd+shift+e")
fcp_share("YouTube — 4K")
fcp_discover_effects()     → every installed effect/transition/title

---

输出文件

默认情况下，修改后的 FCPXML 会写入与输入文件相同的目录，并添加 _modified 后缀。可通过 output_path 参数逐次调用时覆盖， 也可设置规范目录，用于存放相对路径和生成的输出：

export FCP_MCP_OUTPUT_DIR=/your/path

当未设置 FCP_MCP_OUTPUT_DIR 时，FCP_PROJECTS_DIR 仍作为旧版回退值。相对输入路径会在输出目录下解析。

使用 macOS 路径分隔符（:）允许其他输入根目录：

export FCP_MCP_ALLOWED_ROOTS="/Users/me/Movies:/Volumes/Media"

会拒绝位于这些根目录之外的绝对路径输入和符号链接解析后的输入。 对于基于输入文件的操作，显式输出路径可以位于输出目录下，也可以位于输入文件的父目录下。解析后指向同一文件的输入和输出一律拒绝。替换现有目标时，会创建一个同级备份，命名为 <file>.bak.<UTC timestamp>.<transaction UUID>。

实时 FCP、辅助功能和 Compressor 操作均需选择启用：

export FCP_MCP_ENABLE_LIVE_CONTROL=1

离线使用时请保持未设置。运行时和事务事件默认使用文本格式；设置 FCP_MCP_LOG_FORMAT=json 可使用 JSON 行格式。

工作流状态默认存储在 macOS 应用支持目录中。需要隔离时可覆盖：

export FCP_MCP_STATE_DIR=/your/private/state

---

示例

请参阅完整图库，了解工具序列和 工作流拆解。示例提示词：

• “对 hero.fcpxml 运行结构 QC 报告，并修复所有报告中的闪帧。”
• “将这些 .srt 字幕转换为 FCPXML 标题片段，并放到 V2 轨道上。”
• “将我的粗剪 XML 重新导出为 DaVinci Resolve XML，以便进行调色。”
• “列出时间线上的所有片段，然后为所有采访片段批量分配 ‘dialogue’ 角色。”
• “打开当前活动的资料库，定位到第一个标记，然后通过 Compressor 输出 ProRes 422 HQ。”
• “构建一个包含 3 个角色的木偶场景：一个行走，一个说话，一个挥手。时间线时长为 5 秒。”

---

架构

Claude Code / Claude Desktop / any MCP client
        │
        │  stdio (JSON-RPC)
        ▼
   fcp-mcp server (fcp_mcp/server.py, MCP SDK v2)
        │
        ├── fcpxml/parser + writer + models ← rational-arithmetic, defusedxml-hardened
        ├── fcpxml/analysis + validator     ← QC, pacing, flash frames, gaps
        ├── fcpxml/generator + puppet       ← programmatic timeline construction
        ├── fcpxml/diff                     ← A/B timeline comparison
        ├── workflow/                       ← prepare, verify, approve, commit, recover
        ├── private workflow ledger         ← candidates, events, hashes, reconciliation
        ├── fcp_control/ (AppleScript)      ← live FCP when available
        ├── media/ffprobe                   ← clip info, loudness, scenes, frames
        └── Compressor (CLI dispatch)       ← automated encodes
              │
              ▼
        .fcpxml (v1.11+) / EDL / DaVinci XML / FCP7 XMEML / ProRes / H.264

---

故障排除

fcp-mcp: command not found — 确保你安装时使用的 venv 位于 PATH 中，或者在 MCP 配置中使用 venv 的 bin/fcp-mcp 绝对路径。

调用 media_ 时出现 ffmpeg: command not found* — 运行 brew install ffmpeg。FFmpeg 未随软件包一起提供。

fcp_* 工具返回 “Final Cut Pro is not running” — 请先启动 FCP。实时 工具需要 macOS 上有正在运行的 FCP 进程，并且 FCP_MCP_ENABLE_LIVE_CONTROL=1。

fcp_* 工具在较新版本的 FCP 上静默失败 — 与 FCPX 之前的版本相比，FCP 的脚本接口 功能有限。菜单项和键盘快捷键是可靠的途径；某些 JXA 查询需要获得辅助功能权限 （系统设置 → 隐私与安全性 → 辅助功能 → Claude/Terminal）。

fcpxml_* 工具报告结构验证失败 — 对已实现的检查运行 fcpxml_validate。通过此验证器并不能证明与 Apple/FCP 完全兼容。在安装了 Final Cut Pro 的 Mac 上运行 python scripts/apple_dtd_gate.py path/to/result.fcpxml，然后将重要结果导入一个临时的 Final Cut Pro 项目，再依赖该结果。

path_outside_scope — 将媒体位置添加到 FCP_MCP_ALLOWED_ROOTS。外部卷不会自动受到信任。

same_file_forbidden — 选择不同的输出路径。即使调用方明确指定源路径，fcp-mcp 也绝不会 覆盖源文件。

fcpxml_apply_template 返回 unsupported_contract — 模板列表和保存功能仍然可用，但片段替换没有稳定的 模式，因此在 v0.3.0 中仍有意不提供。

导入时测试失败 — 激活 venv 并重新安装：pip install -e ".[dev]"。

---

计划中的工作

请参阅 ROADMAP.md 了解完整计划。重点包括：

• MCP 提示词 — 已发布：qc-check、youtube-chapters、cleanup、rough-cut、beat-sync
• 代理/Resolve 往返流程 — 支持代理的离线/在线工作流

---

致谢

fcp-mcp 由 Adam Steen 和 Claude（Anthropic）共同开发。

许可证

MIT — 详见 LICENSE。