aviutl2-mcp

AviUtl ExEdit2 (AviUtl2) を LLM（Claude Code など）から操作する MCP サーバー。

Claude Code に「1920x1080 30fps のプロジェクトを作って、タイトルテキストを入れて、拡散光をかけて、AviUtl2 で開いて」と指示するだけで、.aup2 プロジェクトを組み立てて実際に AviUtl2 で開くところまで自動化できます。

さらに、ネイティブブリッジプラグイン（plugin/）を導入すると、既に開いている AviUtl2 をリアルタイムに操作できます。 ファイルの書き換え・開き直しは不要で、live_add_object 等のツールを呼ぶと即座にプレビュー画面へ反映されます。詳細は plugin/README.md を参照してください。

動作確認済み環境: AviUtl ExEdit2 version 2.00 beta53a / Windows 11 / Node.js 22。

ダウンロード

Releases から最新版の zip をダウンロード して展開し、setup.bat をダブルクリックするだけで導入できます。手順の詳細は GETTING_STARTED.md を参照してください。

⚠️ 同梱の plugin/build/mcp_bridge.dll（リアルタイム制御用プラグイン）は現時点ではコード署名されていません。導入時にセキュリティソフトが反応することがあります。ソースコードは plugin/src/ に全て公開していますので、気になる方は中身を確認してから使ってください。署名対応の計画は SIGNING.md を参照してください。

以下はこのプロジェクトの技術的な仕組みの説明です。

Related MCP server: OpenCut Controller

仕組み

AviUtl2 のプロジェクトファイル .aup2 は UTF-8・CRLF の INI 風テキストです。このサーバーはそのフォーマットを解析・生成することで、GUI 操作なしにプロジェクトを構築します。

• 実機が保存した .aup2 を parse → serialize してバイト単位で完全一致することをテストで保証（test/roundtrip.test.js）。フォーマットを壊しません。

• オブジェクトは「メディア入力エフェクト → 任意のフィルタ → 描画/再生エフェクト」という AviUtl2 の内部構造どおりに生成します。

• パラメータの書式（拡散光 の 強さ など）は実機が出力したプロジェクトから採取した検証済みの値を使用しています。

安全設計（本体を壊さない）

src/paths.js の assertWritable() で書き込み先を検証し、以下をコードレベルで拒否します。

スクリプトのインストールは C:\ProgramData\aviutl2\Script\MCP\ という専用サブフォルダにのみ行うため、既存のスクリプトや設定を上書きしません。

セットアップ

このリポジトリを好きな場所に clone/展開してください。

cd <展開したフォルダ>\aviutl2-mcp
npm install
npm test        # ラウンドトリップ + MCP 統合テスト

setup.bat（またはsetup.ps1）を実行すると、依存インストールから下記の .mcp.json 作成まで自動化されます。詳しくは GETTING_STARTED.md を参照してください。

Claude Code への登録

このフォルダの直下に .mcp.json を作成すると、Claude Code をこのフォルダで起動したときに自動で読み込まれます。

{
  "mcpServers": {
    "aviutl2": {
      "command": "node",
      "args": ["<展開したフォルダの絶対パス>\\aviutl2-mcp\\src\\index.js"]
    }
  }
}

args にはこのリポジトリの src/index.js への絶対パスを指定してください（setup.ps1 を使えば自動で書き込まれます）。Claude Code をこのフォルダで起動すると aviutl2 サーバーが読み込まれ、/mcp で確認できます。別の場所で使う場合は claude mcp add で登録するか、任意の設定ファイルにこの JSON を追記してください。

環境変数（任意）

• AVIUTL2_EXE_DIR — aviutl2.exe のあるフォルダ（自動検出に失敗する場合）

• AVIUTL2_DATA_DIR — データフォルダ（既定 C:\ProgramData\aviutl2）

提供ツール

オブジェクトの型（add_objects）

• video / image / audio … file（絶対パス）を指定

• text … text（改行可）と text_params（サイズ フォント 文字色 文字装飾 文字揃え など）

• raw … effects でエフェクト列を完全指定（高度な用途）

• 共通: layer frame_start frame_end、draw_params（X Y 拡大率 透明度 合成モード 音量 など）、filters（拡散光 ぼかし ラスター などフィルタ効果の配列）

移動アニメは値を "開始値,終了値,直線移動" の形式で渡します（例 draw_params: { X: "-960,960,直線移動" }）。使えるフィルタ名・パラメータ名は read_docs(doc:"readme") や既存プロジェクトの read_project で確認できます。

使い方の例

Claude Code への指示例：

1280x720 60fps のプロジェクトを C:\Users\<ユーザー名>\Videos\intro.aup2 に作って、 中央にタイトル「新作動画」を縁取り文字で置いて、左から右へスライドインさせて、 AviUtl2 で開いて。

コードから直接叩く例は examples/build-demo.mjs を参照（node examples/build-demo.mjs で demo/demo.aup2 を生成して AviUtl2 で開きます）。

リアルタイム制御（ブリッジプラグイン）

.aup2 ファイルの生成・編集は「開き直し」が必要になりますが、plugin/ に同梱したネイティブプラグイン（.aux2、AviUtl2 公式 SDK の EDIT_SECTION API を使用）を導入すると、既に開いている AviUtl2 に対して名前付きパイプ経由でその場に反映できます。

install_live_bridge を実行 → AviUtl2 を再起動 → live_status で接続確認 → live_add_object / live_update_object / live_delete_object

• 対象は AviUtl2 で現在表示・編集中のシーン（ファイル方式のようなシーン番号指定はない）

• オブジェクトの特定は layer（0始まり）と frame_start の完全一致で行う

• 本体は改変せず、ProgramData\aviutl2\Plugin\aviutl2-mcp-bridge.aux2 という専用ファイル名にのみ書き込む（他のプラグインと衝突しない）

• 仕組み・ビルド方法・IPC プロトコルの詳細は plugin/README.md を参照

スクリプトの配布（MOD）

install_script で自作の Lua スクリプト（アニメーション効果 .anm2 など）を導入し、package_scripts で配布用 zip を作れます。zip は「解凍して出てくるフォルダを ProgramData\aviutl2\Script に入れる」構成になっており、受け取った人は AviUtl2 のプレビュー画面へ D&D するだけでもインストールできます。Lua の仕様は read_docs(doc:"lua") で本体付属の lua.txt を読めます。

このツール自体の配布パッケージを作る

他の人に配れる zip（setup.bat で導入できる完成品）を作るには:

npm run package

release/aviutl2-mcp-vX.X.X.zip が生成されます。node_modules や .git、開発中の一時ファイルは含まれず、 受け取った人がそのまま setup.bat を実行できる最小構成（ソース一式 + ビルド済みの plugin/build/mcp_bridge.dll）になります。 プラグインを最新のソースから作り直したい場合は、先に plugin/README.md の手順でビルドしてから npm run package を実行してください（ビルド済みDLLが無くても、ファイル方式の機能だけを含んだパッケージが作られます）。

配布を受け取った側の手順は GETTING_STARTED.md にまとめてあります。

コード署名について

plugin/build/mcp_bridge.dll は未署名のネイティブDLLです。動画編集ソフトのプロセスに読み込まれ 名前付きパイプで通信するという性質上、セキュリティソフトが警戒する可能性があります。

このプロジェクトは SignPath.io のオープンソース向け無料署名プログラムへの 申請を前提に、GitHub Actions での自動ビルド（.github/workflows/build-plugin.yml） を用意しています。申請〜設定の具体的な手順は SIGNING.md を参照してください。

署名してもセキュリティソフトの警戒が完全になくなるわけではありません（未知の発行元という理由での警告は 減りますが、「動画編集ソフトに注入されIPC通信を行う」という挙動自体への挙動検知は署名の有無に関わらず 残る可能性があります）。SignPathでの審査が難しい場合の代替として、Azure Trusted Signing（月額課金・ 要Microsoftアカウントでの本人確認）や、Sectigo/Certum等が提供する個人向けOV証明書（年額課金・要身分証明） もあります。

注意点

• ファイル方式（create_project/add_objects 等）は、AviUtl2 で既に開いているプロジェクトを外部から編集しても自動では反映されません。編集後は AviUtl2 で開き直してください。逆に、AviUtl2 で編集・保存すると外部の変更は上書きされます。同じプロジェクトを両方から同時に触らないようにしてください。リアルタイムに反映したい場合はブリッジプラグイン経由の live_* ツールを使ってください（上記「リアルタイム制御」参照）。

• add_objects は同一レイヤー・同一シーンでフレーム範囲が重なる追加を拒否します。

• 対応フォーマットは AviUtl2 2.00 beta53a で確認したものです。将来のバージョンでキーが増えても、未知のセクションはパーサが明示的にエラーにするため、気付かず壊すことはありません。

ライセンス

MIT。AviUtl2 本体は同梱しません（各自でインストール）。