DaVinci Resolve MCP (free edition)

davinci-resolve-mcp

Claude Code から DaVinci Resolve 21.1 の無料版を操作できます。

Resolve 21.1 の無料版では、Workspace > Scripts メニューから Python スクリプトが削除され、外部スクリプトの実行がブロックされています。ただし、Lua のメニュースクリプトは引き続き実行できます。このプロジェクトでは、その隙間を利用します。Resolve 内で Lua ブリッジを実行し、外部で小さな Python MCP サーバーを実行します。サーバーは Lua をブリッジに送り、ブリッジは実行中の resolve オブジェクトに対して Lua を実行し、結果を返します。実測では、1 回の呼び出しに約 80～95 ms かかります。ツールは 33 個あり、名前付きツールで対応できない操作には run_lua を利用できます。

必要条件

• macOS
• DaVinci Resolve 21.1.2（無料版または Studio）
• Claude Code
• /usr/bin/python3 に Python 3.9 以降がインストールされていること
• pip のインストールは不要です。サーバーは標準ライブラリのみを使用します。

インストール

git clone https://github.com/kingjamesch/davinci-resolve-mcp.git
cd davinci-resolve-mcp
./install.sh

インストーラーは次の 4 つの処理を行います。

1. 2 つの Lua スクリプトを ~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility/ にコピーします。ブリッジには状態ディレクトリのパスを書き込みます。
2. 状態ディレクトリ ~/Library/Application Support/Blackmagic Design/DaVinci Resolve/ClaudeMCP を、パーミッション 0700 で作成します。
3. ユーザースコープで、サーバーを davinci として Claude Code に登録します。
4. 次の手順を表示します。

インストーラーが表示する次の手順は以下のとおりです。

NEXT STEPS
1) Quit and reopen DaVinci Resolve once (it scans the Scripts menu only at startup).
2) In Resolve: Workspace > Scripts > Claude_MCP_Bridge (do this once per Resolve session; Claude_MCP_Bridge_Stop stops it).
3) In Claude Code run /mcp and check that 'davinci' is connected, then ask for resolve_status.

初回インストール後に、Resolve を一度再起動する必要があります。Resolve は起動時にのみ Scripts フォルダーを読み込みます。

その他のフラグ：

フラグ	効果
--claude-desktop	Claude Desktop の設定にも davinci を追加します。任意です。既存の設定は先にバックアップされます。
--no-claude	Claude Code への登録をスキップします。
--check	インストール済みの内容を報告します。
--uninstall	Lua スクリプトと Claude Code の登録を削除します。状態ディレクトリも削除するには --purge を追加してください。./uninstall.sh でも同じ処理を行います。

Claude Code プラグインとしてインストール

Claude Code だけを使う場合は、リポジトリをクローンする必要はありません。Claude Code 内で次を実行します。

/plugin marketplace add kingjamesch/davinci-resolve-mcp
/plugin install davinci-resolve@davinci-resolve-mcp
/davinci-resolve:setup

プラグインは davinci サーバーを独自に登録します。/davinci-resolve:setup を実行すると、2 つの Lua スクリプトが Resolve の Scripts フォルダーにコピーされます。その後、Resolve を一度再起動し、Workspace > Scripts > Claude_MCP_Bridge をクリックします。プラグインには、Claude が必要とする規則（絶対フレーム、マーカーのルール、Lua の慣用表現、Studio 限定の注意点）をまとめた resolve スキルも含まれています。

プラグインと ./install.sh のどちらか一方を使用してください。両方を使うと、Claude Code に davinci サーバーが 2 つ表示されます（claude mcp remove davinci -s user を実行すると、クローンベースのサーバーが削除されます）。

このサーバーは、検索用として MCP Registry に io.github.kingjamesch/davinci-resolve-mcp の名前で掲載されています。この掲載情報はメタデータのみです。ブリッジを手動で Resolve 内に配置する必要があるため、上記のプラグインまたはクローンからインストールしてください。

日常的な使い方

1. プロジェクトを開いた状態で Resolve を起動します。
2. Workspace > Scripts > Claude_MCP_Bridge をクリックします。Resolve のセッションごとに一度実行してください。
3. Claude Code で、まず resolve_status を呼び出すよう依頼します。ブリッジが稼働しているかどうかがわかります。
4. ブリッジを停止するには、Workspace > Scripts > Claude_MCP_Bridge_Stop をクリックします。

プロンプトの例：

• 「resolve_status を呼び出してから、タイムラインを一覧表示してください。」
• 「現在のタイムラインの 00:00:10:00 に、'fix audio' という名前の赤いマーカーを追加してください。」
• 「/Users/me/Footage/day1 内のすべてをインポートし、そこから Day 1 という名前のタイムラインを作成してください。」
• 「現在のタイムラインを /Users/me/Exports に mp4 でレンダリングするようキューに追加して、開始し、完了したら知らせてください。」
• 「run_lua を使って、ビデオトラック 1 のクリップの色を一覧表示してください。」

ツール

すべての引数を含む完全なリファレンスは、docs/TOOLS.md にあります。コードから生成されています。

• ステータスとプロジェクト： resolve_status、list_projects、get_project_info、get_project_setting、open_project、save_project、set_project_setting、open_page
• タイムライン： list_timelines、get_timeline_info、get_timeline_items、get_timeline_markers、set_current_timeline、set_timecode、create_timeline、add_marker、delete_markers、insert_timeline_element、delete_timeline_items、export_timeline
• メディアプール： list_media_pool、get_clip_properties、create_media_pool_folder、import_media、append_clips_to_timeline
• レンダー： get_render_status、list_render_options、add_render_job、start_render、stop_render、delete_render_job
• エスケープハッチ： run_lua は Resolve 内で任意の Lua 5.1 チャンクを実行します。scripting_api_docs は Blackmagic が同梱する API リファレンスを検索し、Claude が Lua を正しく記述できるようにします。

規則：パスは絶対パス、フレームはタイムライン独自の番号付けによる整数、タイムコードは HH:MM:SS:FF です。トラックとアイテムのインデックスは 1 から始まります。

動作の仕組み

• Claude Code は stdio 経由で server.py を起動します。サーバーは MCP を使用し、ネットワークソケットを保持しません。
• リクエストを送信するため、サーバーはステートディレクトリ内にフォルダーを作成します。リクエストはフォルダー名に 16 進数でエンコードされます。
• Lua ブリッジは 30 ms ごとにそれらのフォルダーを一覧表示し、リクエストをデコードして、resolve オブジェクトをバインドした状態で実行します。
• ブリッジは fu:SetData で応答を返し、Resolve がそれを Fusion.prefs に書き込みます。サーバーはそのファイルをポーリングします。
• 最後の応答は Fusion.prefs に残り、書き込まれてから約 10 秒後にクリアされます。ブリッジも停止時に応答をクリアします。
• 複数の Claude Code セッションで 1 つの Resolve を共有できます。各サーバーはステートディレクトリ内でロックを取得するため、リクエストは一度に 1 つずつ実行されます。

ワイヤーフォーマットは docs/PROTOCOL.md にあります。設計記録は docs/MCP-RECORD.md にあります。

トラブルシューティング

• ツールにブリッジが実行されていないと表示される。 プロジェクトを開いた状態で Resolve を起動し、Workspace > Scripts > Claude_MCP_Bridge をクリックしてから、再試行してください。
• Workspace > Scripts に Claude_MCP_Bridge が表示されない。 インストール後に Resolve が再起動されていません。終了してから再度開いてください。./install.sh --check を実行して、ファイルが所定の場所にあることを確認してください。
• ツールがタイムアウトする。 Resolve にダイアログが表示されている可能性があります。たとえば、Studio へのアップグレード案内や、インポート後のフレームレートに関する質問などです。Resolve でダイアログを閉じてください。また、時間のかかる操作が完了するまでブリッジはブロックされます。
• Studio 専用機能が失敗する。 無料版では Studio 専用機能を使用しないでください。これらの機能は失敗するか、アップグレードのダイアログを開いてブリッジをブロックします。
• 古い davinci-resolve-lite-mcp の Python スクリプトが何も実行しない。 21.1 以降では Python スクリプトが Scripts メニューに表示されず、外部スクリプトの実行もブロックされるため、これらのスクリプトは動作しません。

まだ含まれていない機能

カラーページのノードツール、ギャラリーとスチル、Fairlight、コンパウンドクリップと Fusion クリップ、キーボードとプリセットのインポートまたはエクスポート、プロジェクトのアーカイブと復元、Resolve 起動時のブリッジ自動起動、Claude Desktop の .mcpb パッケージ、Windows。ひとまず、これらの大半は run_lua で対応できます。サーバー環境で DAVINCI_MCP_DISABLE_RUN_LUA=1 を設定すると、ツール一覧から run_lua を削除できます。

セキュリティ対策

• ローカルのみで動作します。サーバーはネットワークポートを開かず、テレメトリーも送信しません。
• 認証情報はありません。ユーザーの識別には、macOS のユーザーアカウントを使用します。
• 状態ディレクトリに書き込める人は誰でも、ユーザー権限で Resolve 内で Lua を実行できます。このディレクトリはモード 0700 で作成されます。
• 破壊的な操作を行うツールには confirm: true が必要です。run_lua は自由度が高いため、Claude には、コードを実行して削除または上書きする前にユーザーに確認するよう指示しています。
• レスポンスのサイズには上限があります。上限を超えた結果には truncated のマークが付けられます。
• Fusion.prefs はユーザーが読み取り可能で、クリアされるまで最後のレスポンスを保持します。
• 停止するには、Stop スクリプトを実行して状態ディレクトリを削除してください。
• サーバーが stderr に記録するのは、ツール名、ステータス、所要時間のみです。引数や結果は記録しません。

開発

テストを実行します：

/usr/bin/python3 -m unittest discover -s tests

ツールを変更した後は、ツールリファレンスを再生成します：

/usr/bin/python3 scripts/gen_tools_doc.py

docs/TOOLS.md が古い場合、またはツールの名前が変更されている場合、テストは失敗します。

レイアウト：

server.py                  stdio entry point
install.py, install.sh     installer, uninstaller (uninstall.sh)
bridge/                    Lua scripts that run inside Resolve
davinci_mcp/               server, transport, prefs parser, Lua encoder, docs index
davinci_mcp/tools/         one module per tool group
docs/                      MCP-RECORD.md, PROTOCOL.md, TOOLS.md (generated)
scripts/gen_tools_doc.py   generates docs/TOOLS.md
tests/                     unit tests and the offline bridge round trip

クレジット

• JSON エンコーダーと、実測したホストに関するいくつかの情報は、MIT ライセンスの saadk408/davinci-resolve-lua-mcp を基にしています。
• 環境設定ファイルを介して Lua を通信経路として使用するアイデアは、AutoSubs に由来します。

ライセンス

MIT。詳細は LICENSE を参照してください。