Shotcut MCP

shotcut-mcp

Shotcut のエンジンである MLT を使い、GUI なしで動画を編集する MCP サーバーです。エージェントはプロジェクトの作成、クリップの追加やトリミング、分割、移動、削除、フィルターの適用、タイトルやクロスフェードの追加、タイムラインの読み込み、melt によるレンダリングを行えます。

出力されるのはロックされた動画ファイルではなく、Shotcut ネイティブの .mlt プロジェクトです。エージェントが作成した編集内容を Shotcut で開き、手動で編集を続けられます。

要件

• Python 3.11+
• MLT の melt が PATH にあること。または、MELT_BIN に完全パスを設定してください。Shotcut をインストールすると melt も含まれます。
  • Linux：sudo apt install melt
  • macOS：Shotcut をインストールしてから、MELT_BIN=/Applications/Shotcut.app/Contents/MacOS/melt を設定してください。
  • Windows：Shotcut をインストールしてから、Shotcut フォルダー内の melt.exe を MELT_BIN に設定してください。Windows のレンダリングは、まだ CI でテストされていません。
• クリップの長さの読み取りとレンダリング結果の確認には、FFmpeg に含まれる ffprobe が PATH に必要です。FFPROBE_BIN で上書きできます。

インストール

uv を使えば、インストール手順なしで実行できます。

uvx shotcut-mcp

または、pip でインストールできます。

pip install shotcut-mcp
shotcut-mcp

サーバーは stdio 経由で MCP 通信を行います。

goose で使う

goose Desktop または CLI

1. goose configure を実行し、Add Extension、次に Command-line Extension を選択します。
2. 名前：shotcut
3. コマンド：uvx shotcut-mcp
4. タイムアウト：600 秒以上。レンダリングには goose のデフォルトより長い時間がかかります。
5. 環境変数 SHOTCUT_MCP_WORKDIR を追加します。また、melt が PATH にない場合は MELT_BIN も追加します。

config.yaml

~/.config/goose/config.yaml に次の内容を追加します。

extensions:
  shotcut:
    enabled: true
    type: stdio
    name: shotcut
    cmd: uvx
    args:
      - shotcut-mcp
    envs:
      SHOTCUT_MCP_WORKDIR: /path/to/your/projects
    timeout: 600

次のように goose に依頼します。「clip1.mp4 と clip2.mp4 から promo というプロジェクトを作成し、それぞれ最初の 5 秒を残してクロスフェードし、タイトル『Launch day』を追加してレンダリングしてください。」

他の MCP クライアントで使う

stdio サーバーを実行できる MCP クライアントであれば使用できます。たとえば、Claude Desktop の claude_desktop_config.json は次のとおりです。

{
  "mcpServers": {
    "shotcut": {
      "command": "uvx",
      "args": ["shotcut-mcp"],
      "env": { "SHOTCUT_MCP_WORKDIR": "/path/to/your/projects" }
    }
  }
}

設定

変数	デフォルト	説明
SHOTCUT_MCP_WORKDIR	~/shotcut-mcp-projects	.mlt プロジェクトとその状態ファイルの保存先
MELT_BIN	melt	レンダリングに使う melt バイナリのパス
FFPROBE_BIN	ffprobe	ソースの長さの読み取りに使う ffprobe のパス

ツール

ツール	説明
create_project	フレームサイズとフレームレートを指定して新しいプロジェクトを作成します
add_clip	ソース動画の一部分をタイムラインの末尾に追加します。クリップの ID を返します
trim_clip	クリップのソースのイン点とアウト点を変更します
remove_clip	クリップを 1 つリップル削除します
move_clip	タイムライン上の新しい位置にクリップを移動します
split_clip	クリップ内の指定位置で 2 つに分割します
remove_segment	タイムラインの一部分をリップル削除します
append_text_overlay	指定した 2 つの時刻の間、タイムラインにテキストタイトルを焼き込みます
apply_filter	クリップに brightness、volume、crop、fadeInBrightness、fadeOutBrightness、fadeInAudio、fadeOutAudio を適用します
set_transition	隣接する 2 つのクリップ間で、映像と音声をクロスフェードします
get_timeline	クリップ、ソースのイン点とアウト点、タイムライン上の位置、フィルター、トランジション、タイトルを含む編集内容全体を返します
project_info	プロジェクトの概要メタデータを返します
render	melt を使ってプロジェクトを動画ファイルにレンダリングします
list_projects	作業ディレクトリ内のプロジェクトを一覧表示します

クリップ ID は呼び出しをまたいで維持されます。編集状態は各 .mlt の隣にある .state.json ファイルに保存され、変更のたびにそこから .mlt が再生成されます。

現在の制限事項

• 映像トラックは 1 つです。複数トラックの映像と音声には今後対応する予定です。
• Shotcut の GUI で手動編集すると、次のツール呼び出しで上書きされます。安全な往復編集には今後対応する予定です。
• set_transition の style オプションは受け付けられますが、現時点でレンダリングされるのはディゾルブのみです。

開発

pip install -e ".[dev]"
pytest

melt がインストールされていない場合、レンダリングテストはスキップされます。

ライセンス

MIT