opencut-controller

🎬 OpenCut Controller（MCP 服务）

🌐 西班牙语版：README.es.md

说明

OpenCut Controller 是一款稳健的 Model Context Protocol (MCP) 服务，可通过 AI 模型（如 Claude 或 n8n 内的 Agent）直接全面自动化控制 OpenCut 视频编辑器。

该服务借助底层的 Playwright，可无缝注入 OpenCut 浏览器环境，让大模型通过编程方式操作时间线、场景、媒体资源、渲染引擎等，从而将 OpenCut 打造成由 AI 驱动的无头视频编辑利器。

---

✨ 主要功能

• 161 个全面的 MCP 工具：以编程方式全面控制 OpenCut 的核心编辑功能。
• 双传输方式支持：通过 stdio（默认）在本地连接，或通过现代 HTTP Streamable 传输方式进行远程集成。
• Playwright 集成：直接连接 OpenCut 网页界面，实时操作应用状态。
• 上下文资源：检查编辑器实时状态、当前项目和时间线轨道。
• 预置 MCP 提示词：为常见的高级编辑任务提供即用型模板。

🚀 安装

请确保系统已安装 pnpm（或 Bun）。

重要

OpenCut Controller 需要旧版 OpenCut（Next.js App Router）——该版本包含完整的编辑器、时间线和状态存储。 当前公开仓库（OpenCut-app/OpenCut）是早期重写版（Rust 核心 + GPUI 桌面应用 + Vite 网页外壳），其编辑器尚未实现，因此无法进行控制。 请使用已归档的旧版仓库： OpenCut-app/opencut-classic——上游目前也推荐使用该版本。

# 1. Clone the legacy OpenCut editor (required for MCP to work)
git clone https://github.com/OpenCut-app/opencut-classic.git
cd opencut-classic

# 2. Clone this MCP controller
cd ..
git clone https://github.com/JXUE0/opencut-controller.git
cd opencut-controller

# 3. Install dependencies (Playwright Chromium installs automatically)
pnpm install

# 4. Patch the Local Editor:
# To enable MCP control, apply small patches to the OpenCut source code.
# We provide an automated script for this:
pnpm run patch-editor ../opencut-classic

# 5. Install & run the editor on port 3001 (the port the MCP expects by default)
cd ../opencut-classic
bun install
cd apps/web && bunx next dev --turbopack -p 3001

提示

pnpm install 命令会自动触发 postinstall 脚本，下载所需的 Playwright Chromium 二进制文件。无需手动设置浏览器！

说明

补丁程序具有幂等性：对已经打过补丁的编辑器再次运行，不会产生任何变化。如果你使用早于 1.32.0 的版本打过补丁，请先从 git 恢复 apps/web/src/components/providers/editor-provider.tsx，再重新运行补丁程序——旧补丁暴露的是状态，而不是状态存储。

⚙️ 配置

变量	默认值	描述
OPENCUT_URL	http://localhost:3001	已打补丁的本地 OpenCut 编辑器 URL。
MCP_HEADLESS	true	设为 false 可在 MCP 工作时查看浏览器。
CHROMIUM_PATH	—	使用指定的 Chromium/Chrome 二进制文件，而非 Playwright 自带的版本。
TRANSPORT_TYPE	stdio	stdio 或 http。
PORT	3002	HTTP 传输端口。
MCP_AUTH_TOKEN	—	HTTP 传输使用的 Bearer 令牌（强烈建议设置）。

约定：所有时间值（startTime、duration、time、trimStart 等）均以秒为单位；控制器会将其转换为 OpenCut 内部时钟刻度。FPS 可使用普通数值（30、29.97）。元素音量以 dB 为单位（-60 到 20，0 = 原始音量）。

💻 用法

根据客户端环境，可使用两种不同的传输协议启动该服务。

1. stdio 传输（默认）

适用于 Claude Desktop 等标准本地 MCP 客户端。

npx -y opencut-controller

直接使用 GitHub 上的最新版本（安装时构建）：npx -y --allow-git=all github:JXUE0/opencut-controller（npm 12 起需要 --allow-git）。 从此仓库的克隆版本运行：pnpm build && node dist/index.js。

2. HTTP 流式传输

适用于与 n8n 等外部工作流工具或远程服务集成。服务监听地址为 http://localhost:3002/mcp。

警告

环境变量语法因操作系统而异。请使用下方对应的命令，以避免出错。

Linux / macOS（Bash）：

TRANSPORT_TYPE=http PORT=3002 npx -y opencut-controller

Windows（PowerShell）：

$env:TRANSPORT_TYPE="http"; $env:PORT="3002"; npx -y opencut-controller

3. 带身份验证的 HTTP

如需安全远程访问，请设置 bearer token：

MCP_AUTH_TOKEN=your-secure-token TRANSPORT_TYPE=http PORT=3002 npx -y opencut-controller

然后在请求中加入 Authorization: Bearer your-secure-token。

🛠️ 可用的 MCP 工具（161 个）

该控制器向大模型提供 161 个高度细分的工具，分类如下：

类别	工具数	说明
📁 项目	16	创建、加载、保存、复制项目，以及更改项目设置。
🎬 场景	6	管理场景生命周期、重命名和活动状态。
▶️ 播放	10	播放、暂停、停止、定位、调节音量和静音。
⏱️ 时间线轨道与设置	10	列出、检查、静音、隐藏轨道；管理时间线设置。
🧩 时间线元素	15	插入、修剪、拆分、移动、复制和更新片段。
✨ 时间线效果	5	应用和调整片段效果。
📌 关键帧	6	添加、调整时间和移除动画关键帧。
🎯 选择/剪贴板	6	选择元素、复制和粘贴。
🕰️ 历史记录	4	撤销和重做。
🎞️ 媒体	7	导入媒体文件并将其放到时间线上。
📝 文本	9	创建和设置文本叠加层的样式。
🎵 音频	8	搜索音乐/SFX 并设置元素音量。
🎨 贴纸/画布	13	添加贴纸；设置画布尺寸、FPS 和背景。
⚙️ 转录/导出	11	根据转录内容生成字幕；导出为 MP4/WebM 文件。
🔖 书签/面板/快捷键	23	时间线书签、UI 面板和快捷键。
🔑 身份验证与存储	9	用户会话和存储。
🌐 API	3	通过 OpenCut 的后端进行健康检查和声音搜索。

说明

OpenCut 的主轨道具有磁吸效果：首个片段始终从 0 开始。要自由定位，请使用叠加元素（文本、贴纸或第二个片段）。未指定 trackId 时，插入元素会自动创建轨道；OpenCut 会删除空轨道，因此 timeline_track_add 会返回说明性错误。

export_project 接受 outputPath，可将渲染后的 .mp4/.webm 文件写入磁盘。

📦 MCP 资源

资源会直接向大模型提供 OpenCut 当前状态的上下文：

• opencut://projects - 所有可用 OpenCut 项目的 JSON 数组。
• opencut://editor/state - 实时跟踪活动项目、场景、播放头时间和播放状态。
• opencut://timeline/tracks - 活动场景中各轨道的详细信息。

🤖 MCP 提示词

复杂操作的快速入门模板：

• create_intro_video - 自动创建包含文本叠加层的 10 秒片头视频。
• add_background_music - 搜索 OpenCut 音效库，并修剪音乐以适应时长。
• apply_transition - 使用指定效果无缝衔接两个片段。

🔌 与 Claude Desktop 集成

要将 OpenCut Controller 连接到本地 Claude Desktop 应用，请将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "opencut-controller": {
      "command": "npx",
      "args": ["-y", "opencut-controller"],
      "env": { "OPENCUT_URL": "http://localhost:3001" }
    }
  }
}

客户端断开连接后，浏览器会自动关闭。

⚠️ 故障排查

• “Playwright browser not found”：确保 postinstall 已成功运行。你可以手动执行 npx playwright install chromium。npm 12+ 默认会阻止安装脚本，因此首次使用前，请通过 npx 执行一次 npx playwright install chromium。
• “PowerShell: The term 'TRANSPORT_TYPE=http' is not recognized”：你在 Windows 中使用了 bash 语法。请改用 $env:TRANSPORT_TYPE="http"; npx -y opencut-controller。
• 连接被拒绝 / ERR_CONNECTION_REFUSED：OpenCut 未在 OPENCUT_URL 上运行（默认端口为 3001，而不是 Next.js 的默认端口 3000）。

提示

开发期间，运行 pnpm run typecheck 检查类型；pnpm run build 会打包 dist/。

1. 错误：window.__opencut is undefined / Editor not ready after 30000ms

原因：你正在尝试将 MCP 服务用于生产环境的 Web 应用（opencut.app）。 解决方法：你必须在本地运行经过补丁修改的 OpenCut 编辑器（pnpm run patch-editor <path>）。生产站点不会公开 MCP 控制所需的内部钩子。如果编辑器无法编译，请检查其终端中是否有找不到模块的错误。

导出说明

MP4 导出会强制使用软件 H.264 编码（--disable-accelerated-video-encode），因为 Windows 硬件编码器会导致 OpenCut 导出器卡住；同时会使用 Chromium 的新无头模式，因为旧版无头 shell 会在渲染时崩溃。

2. 错误：Incompatible React versions

原因：monorepo 中的 react 和 react-dom 版本不匹配。 解决方法：确保根目录 package.json 中两者的版本完全一致（例如 19.2.0），然后运行 pnpm install。

3. 错误：Invalid input: expected string, received undefined（Zod 错误）

原因：apps/web/.env 中缺少环境变量。 解决方法：确保 apps/web/ 中有 .env 文件。我们已更新代码，使大多数变量可选，但某些功能可能仍需要 BETTER_AUTH_SECRET。

4. 连接超时

原因：本地 OpenCut 服务（Next.js）仍在编译。 解决方法：等待编辑器终端中出现 ✓ Ready 后，再启动 MCP 服务。

---

📄 致谢

本项目的原始代码库和构想受到 RavenMeld/OpenCut-MCP 基础工作的启发，并在此基础上构建。我们衷心感谢 RavenMeld 在通过 Model Context Protocol 连接 OpenCut 方面所做的开创性工作。

📄 许可证

本项目采用 MIT 许可证。