opencut-controller

🎬 OpenCut Controller（MCP サーバー）

🌐 スペイン語版を読む：README.es.md

メモ

OpenCut Controller は、AI モデル（Claude や n8n 内のエージェントなど）から OpenCut Video Editor を直接完全に自動化・制御するために設計された、堅牢な Model Context Protocol（MCP） サーバーです。

内部で Playwright を活用し、このサーバーは OpenCut のブラウザー環境にシームレスに接続します。これにより、LLM はタイムライン、シーン、メディアアセット、レンダリングエンジンなどをプログラムから操作できます。OpenCut を、AI 主導のヘッドレス動画編集の強力なツールへと変えます。

---

✨ 主な機能

• 充実した 161 個の MCP ツール：OpenCut の主要な編集機能をプログラムから完全に制御できます。
• 2 種類のトランスポートに対応：stdio（デフォルト）でローカル接続するか、最新の HTTP Streamable トランスポートでリモート接続できます。
• Playwright 統合：OpenCut のウェブインターフェイスに直接接続し、アプリケーションの状態をリアルタイムで操作します。
• コンテキストに応じたリソース：エディターのライブ状態、現在のプロジェクト、タイムライントラックを確認できます。
• 事前構築済みの MCP プロンプト：一般的な高度な編集タスクに使えるテンプレートをすぐに利用できます。

🚀 インストール

システムに pnpm（または Bun）がインストールされていることを確認してください。

重要

OpenCut Controller には Legacy OpenCut（Next.js App Router）が必要です — エディター、タイムライン、ストアが完全に実装されたバージョンです。 現在の公開リポジトリ（OpenCut-app/OpenCut）は、初期段階のリライト版（Rust コア + GPUI デスクトップアプリ + Vite ウェブシェル）で、エディターはまだ実装されていないため、制御できるものがありません。 アーカイブされた Legacy リポジトリを使用してください： 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 より古いバージョンでパッチを適用した場合は、再実行する前に apps/web/src/components/providers/editor-provider.tsx を git から復元してください。以前のパッチはストアではなく、ストアの状態を公開していました。

⚙️ 設定

変数	デフォルト	説明
OPENCUT_URL	http://localhost:3001	パッチを適用したローカル OpenCut エディターの URL です。
MCP_HEADLESS	true	MCP の動作中にブラウザーを表示するには、false に設定します。
CHROMIUM_PATH	—	Playwright のものではなく、特定の Chromium／Chrome バイナリを使用します。
TRANSPORT_TYPE	stdio	stdio または http です。
PORT	3002	HTTP トランスポートのポートです。
MCP_AUTH_TOKEN	—	HTTP トランスポート用のベアラートークンです（強く推奨）。

規則：時間を表す値（startTime、duration、time、trimStart など）はすべて秒単位です。コントローラーが OpenCut の内部ティックに変換します。FPS には通常の数値（30、29.97）を指定します。エレメントの音量は dB 単位（-60 ～ 20、0 = 元の音量）です。

💻 使い方

クライアント環境に応じて、2 種類のトランスポートプロトコルでサーバーを起動できます。

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

安全にリモートアクセスするには、ベアラートークンを設定します。

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

その後、リクエストに Authorization: Bearer your-secure-token を含めます。

🛠️ 利用可能な MCP ツール（161）

コントローラーは、LLM に対して、以下のカテゴリに分類された粒度の細かいツールを 161 個公開します。

カテゴリ	ツール数	説明
📁 プロジェクト	16	プロジェクトの作成、読み込み、保存、複製、および設定の変更を行います。
🎬 シーン	6	シーンのライフサイクル、名前の変更、およびアクティブ状態を管理します。
▶️ 再生	10	再生、一時停止、停止、シーク、音量調整、およびミュートを行います。
⏱️ タイムライントラックと設定	10	トラックの一覧表示、確認、ミュート、非表示、およびタイムライン設定を行います。
🧩 タイムライン要素	15	クリップの挿入、トリミング、分割、移動、複製、および更新を行います。
✨ タイムラインエフェクト	5	クリップにエフェクトを適用し、調整します。
📌 キーフレーム	6	アニメーションのキーフレームを追加、タイミング変更、および削除します。
🎯 選択／クリップボード	6	要素を選択、コピー、および貼り付けます。
🕰️ 履歴	4	元に戻す、やり直すを行います。
🎞️ メディア	7	メディアファイルをインポートし、タイムラインに配置します。
📝 テキスト	9	テキストオーバーレイを作成し、スタイルを設定します。
🎵 オーディオ	8	音楽／効果音を検索し、要素の音量を設定します。
🎨 ステッカー／キャンバス	13	ステッカーの追加、キャンバスサイズ、FPS、および背景の設定を行います。
⚙️ 文字起こし／エクスポート	11	文字起こしから字幕を作成し、MP4／WebM ファイルにエクスポートします。
🔖 ブックマーク／パネル／キーバインド	23	タイムラインのブックマーク、UI パネル、およびショートカットを管理します。
🔑 認証とストレージ	9	ユーザーセッションとストレージを管理します。
🌐 API	3	OpenCut のバックエンドを介して、ヘルスチェックとサウンド検索を行います。

メモ

OpenCut のメイントラックはマグネット式です。最初のクリップは常に 0 から始まります。自由に配置するには、オーバーレイ要素（テキスト、ステッカー、2 つ目のクリップ）を使用してください。trackId を指定せずに要素を挿入すると、トラックは自動的に作成されます。OpenCut は空のトラックを削除するため、timeline_track_add は説明付きのエラーを返します。

export_project は outputPath を受け取り、レンダリングした .mp4／.webm ファイルをディスクに書き込みます。

📦 MCP リソース

リソースは、OpenCut の現在の状態に関するコンテキストを LLM に直接提供します。

• opencut://projects - 利用可能なすべての OpenCut プロジェクトの JSON 配列。
• opencut://editor/state - アクティブなプロジェクト、シーン、再生ヘッドの時間、および再生状態をリアルタイムで追跡します。
• opencut://timeline/tracks - アクティブなシーンのトラックの詳細な内訳。

🤖 MCP プロンプト

複雑な操作をすぐに始められるテンプレート：

• create_intro_video - テキストオーバーレイ付きの 10 秒のイントロ作成を自動化します。
• add_background_music - OpenCut のサウンドライブラリを検索し、音楽を映像の長さに合わせてトリミングします。
• apply_transition - 指定したエフェクトで 2 つのクリップを滑らかにつなぎます。

🔌 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

原因：本番環境の Web アプリ（opencut.app）で MCP サーバーを使用しようとしています。 対処方法：パッチを適用した OpenCut エディターをローカルで実行する必要があります（pnpm run patch-editor <path>）。本番サイトでは、MCP による制御に必要な内部フックが公開されていません。エディターのコンパイルに失敗した場合は、ターミナルでモジュールが見つからないエラーがないか確認してください。

エクスポートに関する注意事項

MP4 エクスポートでは、Windows のハードウェアエンコーダーが OpenCut のエクスポーターを停止させるため、ソフトウェア H.264 エンコード（--disable-accelerated-video-encode）を強制します。また、従来のヘッドレスシェルはレンダリング中にクラッシュするため、Chromium の新しいヘッドレスモードで実行します。

2. エラー：Incompatible React versions

原因：モノレポ内で 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）がまだコンパイル中です。 対処方法：MCP サーバーを起動する前に、エディターのターミナルに ✓ Ready と表示されるまで待ってください。

---

📄 クレジットと謝辞

このプロジェクトの元となるコードベースとコンセプトは、RavenMeld/OpenCut-MCP の基盤となった取り組みに着想を得て、それを基に構築されました。Model Context Protocol を介して OpenCut を接続する先駆的な取り組みを行った RavenMeld に、心より感謝いたします。

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。