DaVinci Resolve Lite MCP

davinci-resolve-lite-mcp

DaVinci Resolve Lite 21.1+（App Store）では利用できません — Python メニュースクリプトがブロックされるため、MCP サーバーを起動できません。21.1 より前の Lite または Studio では動作します。

https://github.com/user-attachments/assets/8429932f-643b-4131-bdf6-dad0d3399137

Claude が DaVinci Resolve Lite でオープニングタイトルを作成します。プレーンな言葉でのリクエストから、insert_fusion_title + style_fusion_title を使い、光彩とズームインのキーフレーム表示を備えた、金色の「GameHelper」Text+ ノードを作成します。

Claude Code などの AI クライアントから DaVinci Resolve を操作できる MCP サーバーです。既存の davinci-resolve-mcp プロジェクトでは操作できない、Python メニュースクリプトを引き続き利用できる 無料版（Lite）ビルド にも対応しています。

無料版では 外部からの スクリプト実行がブロックされますが、独自の Workspace > Scripts メニューから起動した Python スクリプトは引き続き実行できます。このプロジェクトはその経路を利用します。MCP サーバーはメニュースクリプトとして Resolve 内で 実行され、Claude が接続する小規模なローカル HTTP エンドポイントを通じて、Resolve の Python API を公開します。

Claude Code ──HTTP JSON-RPC (MCP)──▶  127.0.0.1:8765/mcp
                                          │   server runs INSIDE Resolve
                                          │   (Workspace > Scripts > Utility)
                                          ▼
                              command queue → main script thread
                                          ▼
                              global `resolve` object → Resolve API

ツール

Claude に自然な言葉で依頼すると、ツールを通じて Resolve を操作します。上記のデモをご覧ください。編集、カラー、レンダー、メディアプール、Fusion のタイトルスタイリングを含む、全 163 ツールの一覧はツールリファレンスをご覧ください。

対応する無料版で動作する理由

• 対応する無料版 Resolve ビルドでは、Scripts メニュー から起動する Python スクリプトを利用できます（制限されるのは 外部からの ネットワークスクリプト実行のみです）。
• メニュースクリプトは resolve オブジェクトをそのまま取得でき、サーバーをホストできるほど長時間ループを実行できます。
• サンドボックス化された Lite アプリには com.apple.security.network.server エンタイトルメントが含まれているため、localhost の待ち受けソケットを開けます。
• 依存関係ゼロ — Python 標準ライブラリのみを使用します。Resolve のインタープリターに pip install するものはありません。

要件

• macOS と DaVinci Resolve Studio、または Workspace > Scripts で Python スクリプトが引き続き利用できる DaVinci Resolve Lite／無料版ビルド。
• Claude Code（または Streamable HTTP トランスポートに対応する MCP クライアント）。

警告

DaVinci Resolve Lite 21.1 以降の互換性の問題： Blackmagic の DaVinci Resolve 21.1 リリースノート および現在のユーザー報告によると、無料版／App Store 版の Lite ビルドでは Python メニュースクリプトがブロックされる場合があります。この場合、MCP ファイルが正しい Fusion/Scripts/Utility フォルダーにインストールされていても、Workspace > Scripts を開くと、 カテゴリフォルダー（Utility、Comp、Edit、Color、Deliver）がすべて空になります。

このサーバーは、Resolve から Python メニュースクリプトとして起動する必要があります。お使いの Lite ビルドで Python スクリプトがブロックされている場合、このプロジェクトを再インストールしても 空のメニューは修正されません。Python メニュースクリプトが引き続き利用できる 21.1 より前の Lite ビルド、 または Studio／ブロックされていないビルドを使用してください。Lua コンソールは開ける場合がありますが、 それだけでは不十分です。bmd.scriptapp("Resolve") が nil を返す場合は、Resolve の スクリプトオブジェクトも利用できません。

インストール

git clone https://github.com/2sem/davinci-resolve-lite-mcp.git
cd davinci-resolve-lite-mcp
./install.sh

または、リポジトリをクローンせずに pip でインストールする場合：

pip install davinci-resolve-lite-mcp
davinci-mcp-install

davinci-mcp-install は install.sh とまったく同じ処理を行います（Lite／Studio の検出方法も、コピーとシンボリックリンクの 使い分けも同じです）。違いは、git チェックアウトではなく pip でインストールしたパッケージからファイルを読み込む点だけです。 davinci-mcp-uninstall で元に戻せます。どちらの方法でも、以下のサンドボックスに関する注意事項が適用されます。また、 サーバーは引き続き Resolve のメニューから起動します。実行を参照してください。

macOS でのユーザーインストールに関する注意。 Defaulting to user installation because normal site-packages is not writeable と表示された場合、pip はコンソールスクリプトを $(python3 -m site --user-base)/bin にインストールしています。このディレクトリは通常 PATH に含まれていません。 コマンドをフルパスで実行するか — "$(python3 -m site --user-base)/bin/davinci-mcp-install" — またはその bin ディレクトリを PATH に追加してください。また、2 つのコマンドの間には & ではなく && を使用してください。 単独の & は pip install をバックグラウンドで実行するため、パッケージが存在する前に davinci-mcp-install が実行されて競合します。

MCP Registry にも io.github.2sem/davinci-resolve-lite-mcp として掲載されています （確認）。 これは見つけやすくするためだけの掲載です。この掲載はメタデータのみで、自動インストール用の packages／remotes エントリーはありません。このサーバーは Resolve に組み込まれた Python インタープリター内で実行する必要があり、 Scripts メニューから手動で起動するため、一般的なレジストリサーバーのように MCP クライアントから起動することはできません。 上記のいずれかの方法でインストールしてください。

install.sh は次のものを配置します。

• 2 つのランチャースクリプトを Fusion/Scripts/Utility に配置します（Resolve が Scripts メニュー用にスキャンするフォルダーです。 Utility はすべてのページに表示されます）。
• resolve_mcp パッケージを Fusion/Scripts/MCP に配置します。Resolve はこのフォルダーを スキャンしないため、ヘルパーモジュールはメニューに表示されません。

Lite のコンテナーパスは自動的に検出されます。

サンドボックスに関する注意（重要）。 DaVinci Resolve Lite はサンドボックス化されており、自身のコンテナー、 ~/Movies、およびユーザーが対話的に選択したファイルのみ読み込めます。これらの場所の外を指すシンボリックリンク （例：~/Projects 内のクローンを指すもの）はサンドボックス化されたアプリからたどることができないため、 メニュースクリプトは何も表示せずに実行されない可能性があります。そのため、Lite では install.sh が コンテナーにファイルをコピーし（サンドボックス化されていない Studio ビルドでのみシンボリックリンクを使用）ます。 更新を取得した後は、./install.sh を再実行してください。

Resolve は Scripts メニュー用にカテゴリフォルダー（Utility / Comp / Tool / Edit / Color / Deliver）だけを列挙します。そのため、ランチャーは Utility に配置し、パッケージは MCP に格納します。

同じサンドボックス制限は、ツールに使用させるファイルパスにも適用されます。 エクスポート／インポート先には ~/Movies（またはアクセスが許可されたその他の場所）を指定してください。 そうしないと、Resolve はファイルの読み書きができません。

実行

1. DaVinci Resolve で、Workspace > Scripts > Utility > davinci_mcp_server を選択します。

   

2. Workspace > Console を開くと、エンドポイントとポートが表示されます。

   MCP endpoint:  http://127.0.0.1:8765/mcp
   Add to Claude Code:
     claude mcp add --transport http davinci http://127.0.0.1:8765/mcp
   

   起動ガイドは Resolve Console（Workspace > Console）に表示されます。 サーバーは継続して実行されるため、停止するまで Console の出力がバッファーに 保持されることがあります。そのため、両方のスクリプトはすべての行をログファイルにも出力します。

   ~/Movies/davinci-resolve-lite-mcp.log
   

   ./logs.sh でリアルタイムに監視できます。（ディレクトリは DAVINCI_MCP_LOG_DIR で変更できます。）サンドボックス化された Lite アプリは ~/Movies への書き込みが許可されているため、このディレクトリを使用します。

   起動すると、すべてのツール呼び出しが Console に 1 行で記録されます （[davinci-mcp] <name> <args> -> ok|error (Nms)）。

   

   アップデートの確認。 brew／CocoaPods と同様に、起動するたびにバックグラウンドで PyPI を確認し、新しいリリースがあれば Console に 1 行の通知を表示します。 起動を妨げることはなく、失敗（オフライン、PyPI の停止など）はログファイルにのみ記録され、 画面には表示されません。DAVINCI_MCP_SKIP_UPDATE_CHECK=1 で無効にできます。

3. Claude Code に登録します（初回のみ）。

   claude mcp add --transport http davinci http://127.0.0.1:8765/mcp
   

   続いて、Claude Code 内で /mcp コマンドを実行し、接続を確認／再接続します。 接続済みのサーバーが一覧表示され、再接続されます。スクリプトの起動時に Claude が すでに実行中だった場合は、/mcp を入力するか、セッションを再起動して davinci サーバーを認識させてください。

4. Claude に Resolve の操作を依頼します。

トラブルシューティング：Workspace > Scripts が空の場合

Workspace > Scripts に想定されるカテゴリーフォルダーが表示されていても、すべてのフォルダーが 空の場合、Resolve がメニュースクリプトを読み込んでいません。再インストールする前に、次の点を確認してください。

flowchart TD
  A[Install MCP scripts] --> B[Open Resolve]
  B --> C{Workspace > Scripts has entries?}
  C -->|Yes| D[Run Utility > davinci_mcp_server]
  C -->|No, all categories empty| E[Resolve is not loading Python menu scripts]
  E --> F{Lite 21.1+ / App Store build?}
  F -->|Yes| G[Use pre-21.1 Lite or Studio/non-blocked build]
  F -->|No| H[Enable scripting in Preferences and restart Resolve]

• DaVinci Resolve Studio／スクリプト設定があるビルドでは、 Preferences > System > General > External scripting using を Local または Network に設定し、保存してから Resolve を完全に再起動してください。

• Python がブロックされる DaVinci Resolve Lite 21.1 以降／App Store 版の場合 （Blackmagic の21.1 リリースノートを参照）、 設定が利用できず、Scripts メニューが空のままになることがあります。これらのビルドでは、 Resolve 内での Python メニュースクリプトの実行が必要なため、この MCP サーバーは起動できません。

• Workspace > Console に引き続き Lua> プロンプトが表示されていても、 Lua コンソールが存在することしか確認できません。次のコマンドで Resolve のスクリプティングオブジェクトが 利用可能か確認できます。

  print("lua ok")
  resolve = bmd.scriptapp("Resolve")
  print(resolve)
  

  2 行目に nil と表示される場合、現在の Lite ビルドでは Lua 経由でも Resolve のスクリプティングオブジェクトが公開されていません。

• 隠しフォルダー Fusion/Scripts/MCP はメニューに表示されません。 対応ビルドでは Utility の下に davinci_mcp_server と stop_davinci_mcp_server のみが表示されます。

ポートの設定（安定性に優れた推奨方法）

デフォルトでは、サーバーは 8765 でリッスンし、そのポートが使用中の場合は 8766、8767、…へ自動的に繰り上がります（別のローカルツールがすでに 8765 を使用している場合があります）。起動のたびにポートの競合でどちらが使われるかが変わる可能性があるため、Claude に登録した URL が変わり、次のような状態になることがあります。

Failed to reconnect to davinci: HTTP 404 at http://127.0.0.1:8765/mcp

ポートを固定するには、小さな JSON 設定ファイルを作成します。この方法でポートを設定すると、そのポートは 固定 されます。サーバーは指定されたポートに正確にバインドし、自動的に繰り上がることはありません。そのため、Claude への登録は一度だけで済み、URL が変わることもありません。

~/Movies/davinci-resolve-lite-mcp.config.json を作成します。

{ "host": "127.0.0.1", "port": 8770 }

なぜ ~/.config ではなく ~/Movies なのですか？ Lite アプリはサンドボックス化されているため、自身のコンテナ、~/Movies、およびユーザーが対話的に選択したファイルしか読み取れません。~/.config はサンドボックスの外にあるため、Lite からは読み取れません（ログファイルが ~/Movies に保存されるのも同じ理由です）。Studio の サンドボックス化されていないビルドでは、そのパスが慣例的なため、サーバーは ~/.config/davinci-resolve-lite-mcp/config.json も確認します。

次にサーバーを再起動し（Scripts > Utility > stop_davinci_mcp_server、続いて davinci_mcp_server）、固定ポートを指定して Claude に一度だけ登録します。

claude mcp add --transport http davinci http://127.0.0.1:8770/mcp

Console のバナーで設定元を確認できます。Port : pinned (from …) — will not auto-increment を探してください。

優先順位（高い順）：DAVINCI_MCP_PORT / DAVINCI_MCP_HOST 環境変数、設定ファイル、組み込みのデフォルト値の順です。環境変数でもポートを固定できますが、Dock から起動した Resolve にはシェルの export が反映されません。永続的に設定するには、設定ファイルが最も簡単です。DAVINCI_MCP_CONFIG=/path/to.json を指定すると、特定の設定ファイルだけが排他的に使用されます。そのパスにファイルが存在しないか、形式が正しくない場合、サーバーは ~/Movies / XDG を読み込まず、組み込みのデフォルト値にフォールバックします。

ポートがすでに変わり、Claude が誤ったポートを参照している場合は、参照先を変更してください。

claude mcp remove davinci
claude mcp add --transport http davinci http://127.0.0.1:<actual-port>/mcp

停止

次のいずれかの方法でサーバーを停止できます。

• メニューから： Workspace > Scripts > Utility > stop_davinci_mcp_server
• ターミナルから： ./stop.sh
• DaVinci Resolve を終了する

メニューの停止スクリプトと stop.sh はどちらも、サーバーの /shutdown エンドポイントに POST し、サーバーの起動時と同じポート範囲をスキャンします。

ポートが自動的に繰り上がるのは、8765 が固定されていない場合のみです。起動のたびに URL が変わらないようにポートを固定するには、 ポートの設定を参照してください。

ツール

パイプライン全体を網羅する163 個のツール：

• ステータスとナビゲーション — ページの切り替え、プロジェクト／タイムラインの設定
• プロジェクトとタイムライン — 読み込み／作成／複製、マーカー、シーンカット、ライフサイクル
• トラック — 追加／削除、有効化／ロック／名前変更
• 編集 — クリップの配置／追加／削除、タイトルとジェネレーター、変形／クロップ／ズーム
• メディアプールとストレージ — インポート／削除、プロパティとメタデータ、タグ付け、ディスクの参照
• カラー — ノードグラフの LUT／有効化、グレードのリセット、スチル
• レンダーとエクスポート — レンダーキュー、フォーマット／コーデック、フレーム／タイムライン／プロジェクトのエクスポートとインポート

各ツールの詳細については、docs/TOOLS.md を参照してください。

すべてのツール呼び出しは、Resolve Console とログファイルに次の形式の 1 行で記録されます：[davinci-mcp] <name> <args> -> ok|error|EXCEPTION (Nms)。

プロジェクトの構成

src/davinci_mcp_server.py        thin launcher (deployed to Scripts/Utility)
src/stop_davinci_mcp_server.py   stop launcher
src/resolve_mcp/                 the server package (deployed to Scripts/MCP, hidden)
    config · logio · connection · bridge · tools · server
tests/test_server.py             offline tests (fake Resolve, no app needed)
install.sh · uninstall.sh · stop.sh · logs.sh
docs/TOOLS.md                    full per-tool reference
fallbacks/                       documented gotchas + fixes

テスト

• オフライン（Resolve もサーバーも不要）— インポート、ディスパッチャー、ツール数のスモークテスト：

  python3 tests/test_server.py
  

• ライブ統合テスト — サーバーの実行中に、各ツールにつき 1 件のテストを実施します（Resolve を開き、プロジェクトとメディアクリップを読み込んだ状態で、davinci_mcp_server を起動します）：

  python3 tests/live_test.py                 # all features
  python3 tests/live_test.py set_timecode    # run the test(s) for given feature(s)
  

  各テスト名はツール名と同じなので、ツールを変更したときは、そのテストだけを実行できます：python3 tests/live_test.py <tool>。テストは元に戻せるように実装されています（一時タイムラインと一時ファイルを使用し、後でクリーンアップします）。ファイル依存のツールとセッションを破壊するツールは、エラーとなるケースを通じて確認します。Studio 専用または負荷の高いツール（例：detect_scene_cuts、render_current_timeline、quick_export）は、理由を添えてスキップします。マーカーや静止画に関する一部のテストは、Resolve セッションがクリーンな状態である必要があります。不安定な場合は、Resolve を再起動してから再実行してください。

コントリビューション

ツールの追加方法、テストスイートの実行方法、標準ライブラリのみを使う制約と Lite 優先の制約、リリースの手順については、CONTRIBUTING.md を参照してください。

対象範囲

このサーバーは無料の Lite エディションを対象とし、そこで動作する API のみを意図的にカバーしています。Studio 専用または有料の機能は Lite では何もしないかエラーになるため、意図的に対象外としています。具体的には、音声の文字起こし、音声からの字幕生成、Magic Mask、手ぶれ補正、スマートリフレーム、Dolby Vision 解析、Voice Isolation、クラウドプロジェクト／データベース管理です。残りの未ラップメソッドは単純なアクセサー（GetUniqueId、キャッシュモード、Fusion コンポジションの内部機能、テイク、ステレオ／3D、レイアウトと焼き込みのプリセット、マット）であり、機能上の不足ではありません。

既知の制限事項

• クリップは名前（現在のメディアプールフォルダー内）または ID（id／ids、任意のビンから解決可能）で指定できます。名前が曖昧な場合や、クリップが別のフォルダーにある場合は、id／ids を指定してください。
• ツールの引数は、各ツールの JSON Schema に照らして検証されます（必須フィールド、基本的な型、列挙値）。形式が正しくない呼び出しには、問題のある引数を示す明確なエラーが返されます。深い階層やネストされたスキーマの制約は、網羅的には検証されません。

セキュリティに関する注意

サーバーは 127.0.0.1 のみで待ち受けるため、このマシンからのみアクセスできます。ポートに接続できるローカルプロセスであれば、DaVinci Resolve を操作できます。信頼できるマシンでのみ実行してください。

サーバーが独自に行う外部通信は、起動時の更新確認のみです（現在のバージョン番号を取得するため、PyPI の公開 JSON API に GET を送信します。ほかのデータは送信されません）。更新確認を無効にするには、DAVINCI_MCP_SKIP_UPDATE_CHECK=1 を設定してください。

ライセンス

MIT — LICENSE を参照してください。