davinci-resolve-lite-mcp

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

平易な言葉のリクエストから、Claude が DaVinci Resolve Lite でオープニングタイトルを構築する様子 — 金色の「GameHelper」Text+ ノードにグローとズームインのキーフレーム演出を加えたもの。insert_fusion_title + style_fusion_title を使用。

Claude Code などの AI クライアントが DaVinci Resolve を操作できるようにする MCP サーバーです。既存の davinci-resolve-mcp プロジェクトでは操作できない、無料（Lite）版にも対応しています。

無料版は外部スクリプトをブロックしますが、Resolve 自身の 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 に依頼してください。Claude がツールを通じて Resolve を操作します — 上記のデモを参照してください。全 163 ツールの詳細（編集、カラー、レンダリング、メディアプール、Fusion タイトルのスタイリング）は ツールリファレンス をご覧ください。

Related MCP server: resolve-mcp

無料版でも動作する仕組み

• 無料版の Resolve は、Scripts メニューから実行するスクリプトを許可しています（外部からのネットワークスクリプトのみが制限されています）。

• メニュースクリプトは resolve オブジェクトを自動的に取得でき、サーバーをホストするのに十分な長時間実行ループも動作させられます。

• サンドボックス化された Lite アプリには com.apple.security.network.server エンタイトルメントが含まれているため、ローカルのリッスンソケットを開けます。

• 依存関係ゼロ — 純粋な Python 標準ライブラリのみ。Resolve のインタプリタに pip install するものは一切ありません。

必要条件

• macOS に DaVinci Resolve（Lite / 無料版または Studio）がインストールされていること

• Claude Code（または Streamable HTTP トランスポートに対応した任意の MCP クライアント）

インストール

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 クライアントから起動することはできません。インストールは上記の 2 つの方法のいずれかで行ってください。

install.sh は以下を配置します:

• 2 つのランチャスクリプトを Fusion/Scripts/Utility に（Resolve が Scripts メニュー用にスキャンするフォルダ。Utility はすべてのページに表示されます）。

• resolve_mcp パッケージを Fusion/Scripts/MCP に — ここは Resolve がスキャンしないフォルダなので、ヘルパーモジュールを メニューに出ません。

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

サンドボックスに関する注記（重要）。 DaVinci Resolve Lite はサンドボックス化されており、自分のコンテナ、~/Movies、対話的に選択したファイルしか読み取れません。これらの場所の外（例: ~/Projects 配下のクローンなど）を指すシンボリックリンクは、サンドボックス化されたアプリケーションからは 追従できません。そのためメニュースクリプトが静かに動作しないことがあります。そこで install.sh は Lite ではファイルをコンテナ内にコピーします（シンボリックリンクを使うのは、サンドボックス化されていない 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 を設定します。）~/Movies を使うのは、サンドボックス化された Lite アプリがそこへの書き込みを許可されているためです。

   起動後、すべてのツール呼び出しは 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 を操作してもらいます。

ポートの設定（固定、推奨）

デフォルトでは、サーバーは 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-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 を read まず、組み込みデフォルトに戻ります。

もしポートがすでにずれて 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、quit_export）は理由付きでスキップされます。マーカーやスチルの一部のテストは Resolve のセッション状態がきれいであることに依存するため、動作が不安定なときはインスタンスを再起動してから再実行してください。

コントリビューティング

ツールの追加方法、テストスイートの実行方法、stdlib-only / Lite 優先の制約、リリースフローについては CONTRIBUTING.md を参照してください。

スコープ

このサーバーは無料（Lite）版 を対象とし、意図的に Lite で動作する API のみをカバーしています。Studio 専用 / 有料の機能は意図的に除外しています（Lite では何もしないかエラーになるため）。具体的には、オーディオ文字起こし、音声からの字幕生成、Magic Mask、スタビライズ、Smart Reframe、Dolby Vision 解析音声分離、そしてクラウドプロジェクト / データベース管理などです。残りの未対応メソッドは、単純なアクセサ（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](LICENSE)を参照してください。

Wait, I used "エラーを返します" and earlier "問題のある引数を明示す? I wrote "問題のある引遡及" etc. Let me be careful:

"不正な呼び出しが返します" - I'm rewriting. The final:

"不正な呼び出しは、問題のある引数を明示する明確なエラーを返します。"

Should be fine. In my previous draft I had "問題のある引いた" — no, I'll write carefully:

"不正な呼び出しは、問題の所在を示す明確なエラーを返します。" — This indicates the specific argument. I want "naming the offending argument" = "問題のある引数を明示する". Let me use:

"不正な呼び出しは、問題のある引数を明示する明確なエラーを返します。"

OK.

Also first bullet: "例" - Actually keep "(例)" out: "**name**（現在のメディアプールフォルダー内）または**id**（`id`/`ids`、どのビンでも解決可能）で指定できます。" — I shouldn't add "例". Let me stick with:

"クリップは、**名前**（現在のメディアプールフォルダー内）または**id**（`id`/`ids`、どのビンでも解決可能）で指定できます。 Names are ambiguous or the clip is in another folder."

Correct.

Final message should be just the translation.

Let me make sure there's no extraneous code fence. I'll output the## 既知の制限

* クリップは**名前**（現在のメディアプールフォルダー内）または**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](LICENSE)を参照してください。