mmd-mcp：Windows 上の MCP で MikuMikuDance の操作と MME 設定を行う

mmd-mcp は、Windows 向けの stdio MCP サーバーで、MikuMikuDance（MMD）の操作と MME エフェクト設定をプログラム的に行うためのものです。適した前提条件は明確です。Windows 上で、自分で MMD 9.32 x64（日本語版。サーバーはサポート外のバージョンを拒否します）を起動済みであり、かつソースからのビルドインストール（Python x64 と Visual Studio 2022/Build Tools の C++ デスクトップ開発コンポーネントが必要）に同意できること。MMD を自動起動することも、ネットワークをリッスンすることもありません。これらの条件を満たさない環境や、ビルドツールチェーンを扱いたくない場合には、第一候補にはなりません。

向いている人

• Windows 上で MMD アニメーション制作を行い、モデル・カメラ・ライト・物理・タイムラインをプログラム的に調整したり、MME の EMM エフェクト割り当てを編集したり、AVI 動画を出力したりしたい人。
• 検証環境は日本語版 MMD 9.32 x64、日本語 Windows、Python 3.10 x64。他の MMD バージョンは拒否されるため、それ以外のバージョンのユーザーは非サポートと考えるべきです。
• 向いていない人：macOS/Linux ユーザー、MMD をまだインストールしていない人や非検証バージョンを使う人、Visual Studio の C++ コンポーネントを入れたくない人。公式の情報では macOS/Linux 対応には言及がなく、この点は不明です。

3 分で最初の試行を完了するには

注意：このメインパスは実際に 3 分で完了するものではなく、DLL のソースビルドにはある程度時間がかかります。「3 分」とはステップ数が少ないことを指します。

前提条件：

1. Windows 環境で、Python x64 がインストール済み（検証環境は 3.10 x64）。
2. Visual Studio 2022 または Build Tools がインストール済みで、C++ デスクトップ開発コンポーネントにチェックを入れていること（ネイティブ DLL のビルド用）。
3. 日本語版 MMD 9.32 x64 を起動済み——サーバーは MMD を自動起動しません。

インストール（リポジトリのディレクトリで、公式が提示している PowerShell コマンド）：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
cmd /c scripts\build_native.cmd

3 つ目のコマンドでネイティブ DLL がビルドされます。これは必須ステップで、ビルド成果物はローカルに置かれます。

MCP クライアントへの登録（stdio 方式）。公式のサンプル設定：

"command": "C:/Tools/mmd-mcp/.venv/Scripts/python.exe",
"args": ["-m", "mmd_mcp.server"]

パスは自分の venv の場所に置き換えてください。

最初の呼び出しには mmd_list_windows を推奨します。ウィンドウの一覧を取得するだけでシーンを変更しないため、最もリスクの低い初回呼び出しです。成功のサインは、現在の MMD ウィンドウ一覧とその hwnd が返ってくることです。複数の MMD インスタンスを起動している場合は、以降のすべての呼び出しで mmd_list_windows が返した hwnd を渡す必要があります。mmd_list_windows に readOnlyHint が付与されているかは公式情報には記載がないため、どのツールもゼロリスクとは考えないでください。

その他のインストール方法：公式が提示しているのは上記のソースインストールのみで、pip パッケージやプリビルドバイナリの説明は提供されていません。

使用例

例 1：接続確認とマルチインスタンス管理。シーン：クライアントを設定し終えたところで、MMD を見つけられるか確認したい。mmd_list_windows を呼び出し、返されたウィンドウ一覧と hwnd を確認します。MMD が 1 つだけなら、その後は他のツールを直接呼び出せます。複数起動している場合は、公式の説明どおり対応する hwnd を各呼び出しに渡してターゲットを指定します。ここまで確認できるのはウィンドウ列挙と hwnd の受け渡しの仕組みで、より細かい出力形式は実際の返り値を参照してください。

例 2：カメラキーフレームの一括書き込みと動画のエクスポート。シーン：モーションを作成し終え、カメラワークをプログラム的に設定して AVI を出力したい。公式の v0.3.0 は 50 個のツールを提供しており、そのうち mmd_batch_camera_keys でカメラキーフレームを一括書き込みでき、mmd_export_video で AVI を出力できます。この 2 つはいずれも現在の MMD プロジェクトへの書き込み操作である点に注意してください。キーフレームの書き込みと動画のエクスポートはプロジェクトの内容を変更・生成するため、呼び出し前に現在開いているプロジェクトが変更可能であること、またはバックアップ済みであることを確認してください。これらのツールに取り消し手段があるか、またエクスポートパラメータの詳細についても公式情報には記載がないため、呼び出し前にクライアント側で具体的なパラメータ定義を確認してください。

使用上の境界

• 読み書きの性質：50 個のツールには、ウィンドウ/シーンの照会系に加え、モデル選択、ボーン/カメラキーフレームの一括書き込み、EMM エフェクト割り当ての読み書き（mmd_read_effect_assignments / mmd_write_effect_assignments）、AVI エクスポートなどの書き込み操作が含まれます。書き込み操作は、開いている MMD プロジェクトに直接作用します。
• 環境の縛り：検証環境は MMD 9.32 x64（日本語版。公式は特定の SHA-256 で検証）に限定され、サポート外のビルドは拒否されます。
• 前提と副作用：MMD は事前に手動で起動しておく必要があります。サーバーは MMD を自動起動せず、ネットワークもリッスンしません。マルチインスタンス時は hwnd を渡してターゲットを指定しないと、対象が曖昧になります。
• ローカルへの書き込み：インストール時にローカルに venv を作成しネイティブ DLL をビルドします。これは必要なローカル変更です。
• 未確認事項：ツールに取り消しメカニズムがあるか、各書き込み操作のパラメータの詳細、および中国語/英語 Windows や他の Python バージョンとの互換性については、公式情報に記載がありません。情報が欠けていることはリスクがないことを意味しません。書き込み操作を行う前に、必ず自分でプロジェクトをバックアップしてください。