fcptool MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
fcptool-mcp
把 Final Cut Pro 13 自带的官方命令行工具 fcptool 封装成本地 MCP 服务,任何支持 MCP 的 coding agent(Claude Code、Codex、Grok CLI、Cursor、opencode……)都能直接操作 Final Cut Pro 的资源库、事件和 FCPXML。
标准协议:stdio(默认)+ Streamable HTTP(
--http),每个工具同时返回structuredContent和 JSON 文本,带readOnlyHint/destructiveHint注解。为性能设计:fcptool 每次启动固定 ~2.3 s,本服务通过合并调用、变更感知缓存、批处理 DAG、同库串行/跨库并行、以及不走 fcptool 的快路径(DTD 校验 ~5–50 ms、FCPXML 解析、Spotlight 查找、lsof 占用检测)把调用次数降到最低。
对 Agent 友好:稳定错误码 + 修复提示;FCPXML 可以直接内联传入;导出时一并返回解析后的时间线摘要。
fcptool 的完整调研见 docs/fcptool-reference.md(命令、JSON 结构、错误、锁、性能实测)。
环境要求
macOS + Final Cut Pro 13.0+(fcptool 位于
Final Cut Pro.app/Contents/MacOS/fcptool)Node.js ≥ 20
系统自带
xmllint(快速校验用;缺失时自动回退到 fcptool)
Related MCP server: fcp-mcp-server
安装
git clone <this repo> fcptool-mcp && cd fcptool-mcp
npm install && npm run build
node dist/index.js --help下文的 /ABS/fcptool-mcp 换成你的实际路径。用 nvm 的话,node 最好写绝对路径(which node),因为 GUI 客户端不一定继承你的 shell PATH。
接入各个 Agent
Claude Code
claude mcp add fcptool -s user -- node /ABS/fcptool-mcp/dist/index.jsCodex CLI(~/.codex/config.toml)
[mcp_servers.fcptool]
command = "node"
args = ["/ABS/fcptool-mcp/dist/index.js"]或 codex mcp add fcptool -- node /ABS/fcptool-mcp/dist/index.js
Grok CLI
grok mcp add fcptool node -- /ABS/fcptool-mcp/dist/index.js # 写入 ~/.grok/config.toml
grok mcp doctor fcptool # 应显示 handshake OK / 14 toolsCursor(~/.cursor/mcp.json)/ 其它 mcpServers 格式的客户端
{ "mcpServers": { "fcptool": { "command": "node", "args": ["/ABS/fcptool-mcp/dist/index.js"] } } }opencode(opencode.json)
{ "mcp": { "fcptool": { "type": "local", "command": ["node", "/ABS/fcptool-mcp/dist/index.js"], "enabled": true } } }HTTP(多个 Agent 共享一个进程/缓存)
node dist/index.js --http --port 8765 # http://127.0.0.1:8765/mcp ,只监听本机,带 Host 校验
claude mcp add --transport http fcptool http://127.0.0.1:8765/mcp已在本机验证:
Claude Code:headless 调用
fcp_status返回真实数据Grok CLI:
grok mcp doctor显示 handshake OK(protocol 2025-11-25),发现 14 个工具;grok -p无交互模式下由真实模型调用fcp_status,返回 13.0 / 1.15·1.14·1.13 / 当前打开的库Codex CLI 0.171.0:
codex mcp add/list接受配置;codex exec发现全部 14 个工具,并通过 MCP 实际调用fcp_status拿到真实结果(模型端使用本地模拟的 Responses API,因此不需要 OpenAI 凭证)MCP SDK 客户端:stdio 与 HTTP 均通过
工具
工具 | 作用 | fcptool 调用数 |
| 版本、catalog、可导出/可校验的 FCPXML 版本、元数据视图、FCP 是否运行及打开了哪些库 | 0(启动时预热缓存) |
| 用 Spotlight(未索引目录回退遍历)查找 .fcpbundle,并标注是否被 FCP 打开 | 0 |
| 一次返回 info + settings + events;info 与其余并行;重复读取走缓存 | 0–3 |
| 新建库,可同时建多个事件、设置参数 | 1 + N |
| 读取或修改库设置,返回 | 1 |
| 升级 catalog(不可逆) | 1 |
| 事件列表 / 批量新建 / 跨库复制(媒体选项、进度通知) | 1 / N / N |
| 按文档版本对 FCP 自带 DTD 校验,带行号; | 0(快路径) |
| 本地解析 FCPXML:格式、素材、事件、项目时长/时间码、主故事线、标记、关键词、效果、字幕文本 | 0 |
| 路径或内联 XML 导入到新库/已有库;先做 DTD 校验,冲突策略 cancel/keep-both/replace | 1 |
| 导出整库为 .fcpxml/.fcpxmld,同时返回解析摘要( | 1 |
| 一次往返执行多达 100 个操作:涉及同一路径的按顺序执行,不同库并行 | Σ |
资源:fcptool://reference(本调研文档)、fcpxml://dtd/{version}(FCP 自带的 1.0–1.15 DTD,Agent 手写 FCPXML 前可读)。
典型工作流:让 Agent 改时间线
fcptool 不能直接编辑时间线,修改项目要走 FCPXML:
fcp_xml_export { library, inspect: "timeline" }→ 拿到导出文件路径和时间线结构Agent 编辑 XML(可读
fcpxml://dtd/1.15对照结构)fcp_xml_validate { path }(~50 ms,错误带行号)fcp_xml_import { path, into, conflictResolution: "replace" }
性能设计
问题(实测) | 处理 |
每次调用固定 ~2.3 s | 合并调用、缓存、batch;能不调 fcptool 的都不调 |
同库并发 → 4 个里 3 个报 | 每库 FIFO 锁(多库操作一次性入队,不会死锁);全局进程池(默认 cores/2,2–6) |
读操作也会改动库内文件 mtime | 缓存指纹在本次调用之后采集(几百 µs 的 stat),别人改过才会失效;本服务的写操作主动失效 |
库被 FCP 打开 | lsof 判断持有者:被 FCP 占用立即返回 |
客户端取消 | 只读命令立即终止;写命令跑完,避免库写一半 |
校验要 2.3 s 且没有行号 | xmllint + 同一份 DTD,5–50 ms,带行号 |
错误码
所有失败返回 isError: true 和 {error: {code, message, hint?, details?}}:
FCPTOOL_NOT_FOUND · LIBRARY_LOCKED · NOT_FOUND · ALREADY_EXISTS · INVALID_ARGUMENT · NEEDS_UPGRADE · VALIDATION_FAILED · TIMEOUT · CANCELLED · FCPTOOL_ERROR
配置
环境变量 | 默认 |
|
|
| — |
| cores/2(2–6) |
| 600000 |
| 设为 |
安全约定
路径必须是绝对路径(或
~/),因为服务进程的 cwd 与 Agent 不同。导出永不覆盖已有文件;
library_create/newLibrary不会覆盖已有路径。导入默认
conflictResolution: "cancel";默认不升级旧库(autoUpgrade需显式传入)。不会替你关闭 FCP 中打开的库。
测试
npm test # 构建 + 单元测试 + 端到端测试(真实 fcptool,在临时目录里建库,不碰你的库)端到端测试中"被 FCP 打开的库"一项只对该库执行会被拒绝的只读命令。
局限
能力上限即 fcptool:库/事件/设置/FCPXML 进出。不能渲染、导出影片、删除事件或直接控制 FCP 界面。
xml export只能导出整个库。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
A paid remote MCP for HyperFrames, built to return verdicts, receipts, usage logs, and audit-ready J
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
Related MCP Servers
- AlicenseAqualityAmaintenanceThe first MCP server for Final Cut Pro. 53 tools that parse, edit, and generate FCPXML timelines via natural language. Health checks, flash frame detection, chapter markers, rough cuts, NLE export. 912 tests, MIT licensed.153,797 PyPI157MIT
- FlicenseNot gradedqualityAmaintenanceEnables Claude and other MCP clients to read, edit, generate, and validate Final Cut Pro XML timelines with operations for trims, splits, markers, roles, transcripts, keyframes, speed curves, and cross-NLE export, plus pushing edits into a running Final Cut Pro.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude and other MCP clients to read, edit, and generate real Final Cut Pro timelines from FCPXML, including cut detection, markers, roles, silence removal, transcript-based editing, cross-NLE export, and pushing changes into a running Final Cut Pro. Every write is journaled and undoable, with validation and safety checks for reliable timeline edits.-
- FlicenseNot gradedqualityAmaintenanceEnables an MCP client like Claude to read, edit, and generate real Final Cut Pro timelines from exported FCPXML, covering cut and flash-frame detection, silence and gap removal, markers, keyframes, speed ramps, transcript-based editing, cross-NLE export, and pushing the result into a running Final Cut Pro. Every write is journaled with its sha256 so changes can be undone and unreviewed cuts refused.-