mcp-vroid

VRoid Studio の GUI（グラフィカルユーザーインターフェース）を操作する MCP サーバーです。あらゆる MCP クライアント（Claude Code など、プロトコルを話せるクライアント）に対して、アプリの起動、画面の確認、画像内のウィジェットの検出、クリックやタイプ入力、パラメータの設定、.vrm のエクスポートを行う一連のツールを提供します。対象環境は Arch + Hyprland（Wayland） で、VRoid Studio は Steam/Proton 配下で動作します。

VRoid Studio にはスクリプト用 API が無いため、このサーバーは利用可能な唯一の方法で動作します。ウィンドウをスクリーンショットし、OCR と色の一致を頼りに位置を見つけ、実際のポインターとキーボードイベントを注入します。

   grim ──► PNG ──► tesseract / cv2 ──► (x, y) ──► virtual pointer / XTEST
    ▲                                                        │
    └────────────────────  screenshot again  ◄───────────────┘

サーバーの中核は、私の arrakis プロジェクトにある tools/vroid-driver スパイクです。ここでは mcp_vroid.driver としてベンダリングしており、同じコードを MCP クライアントがインストールして起動できるように再パッケージしています。

必要条件

Python の依存関係（uv sync でインストール）:mcp、pillow、numpy、opencv-python-headless、pytesseract、python-xlib。

Related MCP server: blockout-mcp

インストール

git clone https://github.com/nhodges/mcp-vroid
cd mcp-vroid
uv sync                 # virtualenv + dependencies
bash native/build.sh    # builds native/vpointer  <-- REQUIRED, not optional

native/build.sh は zwlr_virtual_pointer_unstable_v1(native/protocols/ に同梱)向けの約 150 行の C クライアントをコンパイルします。これが無いと、すべてのポインターツールは native/vpointer missing で失敗します。vroid_status はその有無を報告します。

なぜ C ヘルパーなのか:ydotool は基準のマシンにインストールされておらず、/dev/uinput は 0600 root:root なので、evdev による注入には sudo か udev ルールが必要です。Wayland の仮想ポインター・プロトコルはどちらも不要で、実際のコンポジタのカーソルを動かし、どのウィンドウでも機能します。

クライアントに登録する

Claude Code:

claude mcp add vroid -- uv run --directory /path/to/mcp-vroid mcp-vroid

一般的な mcpServers JSON:

{
  "mcpServers": {
    "vroid": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-vroid", "mcp-vroid"]
    }
  }
}

クライアントは多くの場合、 サニタイズされた環境 でサーバーを起動します。このサーバーは、起動時に XDG_RUNTIME_DIR、WAYLAND_DISPLAY、HYPRLAND_INSTANCE_SIGNATURE、DISPLAY を実行時ディレクトリから復元します（src/mcp_vroid/session_env.py）。これにより、環境が変わっても hyprctl/grim/XTEST は動作します。vroid_status は何を補完したかを表示します。すでに環境にある値は優先されます。

任意の環境変数:

ツール

ライフサイクル

表示

操作（生の入力）

操作（フロー）

操作系のツールは、まず最初に VRoid がフォーカスされていることを確認し、 フォーカスが VRoid Studio のウィンドウでなければ動作しません。

操作方法

基本的なループは、 スクリーンショット → 確認 → 位置を探る → アクション → もう一度スクリーンショット。

1. vroid_launch()

2. vroid_screenshot() をして 画像をを見る

3. 座標を得るために vroid_find_text("Export") （または vroid_find_button() ）

4. vroid_click(x, y) — 座標は常に「新しく取った」キャプチャから取得します

5. vroid_screenshot() で実際に何が起きたかを確認

試行錯誤して得られた知恵:

• 全体を読め。 「Close Hairstyle Editor」の確認モーダルが画面の中央にあったのに、上位 60 px だけを知らせていたため 6 回失敗しました。

• 3D ビューポートの差分で判断しない。 VRoid は毎フレーム ディザリングされるため、何もしていないのに画像全体の差分は ~0.98 になる。UIが define 部分を見ること。

• スライダードラッグより数値ボックスを使う。 vroid_set_slider は正確な値をタイプします。ドラッグはボックスの無いコントロール専用。

• 主要ボタンはテキストでなく色で見つける。 青いところにピンクーの代わり灰色ピルがある場合、必須項目が空であることをアプリが示しています。

• 2560×1440 の全フレームの OCR は約10 秒です。region を指定してください。

座標空間

ここに3つの異なる座標空間があります:

ツールは既定では 画像ピクセル（空間 "space="image"）で取得・戻納し、内部で変換します。vroid_find_text の出力/入力をvroid_click にそのまま渡せるという立地です。MCP_VROID_MAX_IMAGE_PX で送信された画像がダウンスケールされている場合、そこから読み取る座標は、報告された downscale 値の逆数で乗算してから使ってください。もしくは、常に native ピクセルを返す vroid_find_text を利用するば良い。

UI マップ（VRoid Studio 2.14.0、English）

座標のキャプチャ 2560×1440 (= fullscreen window) の image px。これら位置はあくまでヒントで、ツールはまず OCR で探索します。

起動画面 — Create New + カードは ≈ (118, 218)、キャプションは (118, 328)。右上の New / Open は (2439, 99) / (2495, 100)。その下にサンプルモデルのグリッド。Create New を押すと "Select a base to start with" というモーダルが開き、Fem (1199, 862) と Masc (1359, 862) のキャプションが並ぶ — キャプションの約 100 px 上のサムネイルをクリックする。

エディタ — タブ列は y ≈ 23：Face 97・Hairstyle 198・Body 302・Outfit 392・Accessories 509・Look 622。ハンバーガーメニュー ☰（29, 23）→ 保存 (Ctrl+S)、名前を付けて保存… (Ctrl+Shift+S)、インポート／一括書き出し、元に戻す／やり直す、モデル選択へ戻る — Escape ではこのメニューは閉じない。他の場所をクリックする。右上のツールバー：カメラ (2415, 23)、共有／書き出し (2464, 23)、ケバブ ⋮ (2512, 23)。左のアイコンレール（x ≈ 24、先頭アイコンは y ≈ 77、以降は約 48 px ごと）は、現在のタブのサブカテゴリ。左パネルは Presets／Custom があるプリセットグリッド（y ≈ 120）。右パネルはカスタマイズ、続いてパラメーター。

右パネルのコントロール

Body のパラメーターは Model's Height : 161.2 cm から始まり、Fem Height、Masc Height、Body Size、Head Size、Head Width、Head Tip (Y)、Neck Length/Thickness/Width、Soften Collarbone、…。Face のパラメーターは Eye Size X/Y、Eyes Position (X/Y)、Rotate Eye Socket、Inner/Outer Eye Slant、Iris Size X/Y、Gaze (Y)、…（約 40 行；ツールが自動でスクロールしてくれる）。

ヘアエディター — Hairstyle タブ → 左のアイコン群から部品アイコン → Custom サブタブ → + Create New → 右パネル Edit Hairstyle。中には、Add Freehand Hair Guides／Add Procedural Hair Guides、Hair Groups リスト、ツールパレット（330 / 365 / 398 / 432, 83）、アンドゥー (76, 23) / (133, 23) がある。離れると確認が出る：(23, 23) の ✕ で Close Hairstyle Editor モーダルが開き、Save as new item／Overwrite／Close without saving を選ぶ。

VRM 書き出し — 共有アイコン (2464, 23) → Export as VRM → 全画面の書き出しページで、青い Export ピルバーは ≈ (2413, 197) → VRM Settings モーダル（中央、約 x 1000–1560、スクロール可能）：Export Format のラジオ VRM1.0／VRM0.0、Avatar Name 必須、Version、Creators 必須、著作権／連絡先／参考文献、利用条件のチェックボックス。Export ピルバーは、必須項目が両方埋まるまで グレーで無効のまま → Wine の保存ダイアログ（独立ウィンドウ、タイトル Export）：File name: フィールドはフォーカス＆選択済みで開くので、Windows パスを打ち込めば上書きされ、Return で既定ボタンを 起動する。Proton のプレフィックスは Z:\ を / にマップするため、/home/nuri/x は Z:\home\nuri x になる。OCR で見つかった Save をクリックしてはダメ — Save in: ラベルが同じ needle に一致してしまうから。

壊れやすい点

• OCR が位置特定の全部。 小さな、文字間隔が空いた、または明るい背景に薄い文字のラベルは分割・欠落する（Export → E + xport）。アイコンにはテキストが一切無いので、そのアンカーはウィンドウの割合で直書きされており、pixiv が UI を組み直すとずれる。

• 固定アンカーは 2560×1440、スケール 1.25 で校正している比率。 別 のモニターでは fメモする必要がある。

• モーダルは検索範囲の外に出て、クリックを静かに飲み込む。

• タイミング。 ベースを選んでから 3D ビューポートが表示されるまで約 5 秒。書き出しは 5〜30 秒（重いモデルはより長い）。

• Wine ダイアログは独立したウィンドウで、独自のクラスとジオメトリを持つ — そこで vroid_screenshot(whole_screen=true) を使う。

• 言語。 この説明は英語UIを前提としている。VRoid が日本語で表示される場合は、ケバブ ⋮ → Settings → Language で切り替える。

• アイドル時のスクリーンセーバーが、実行途中にセッションを乗っ取ることがある。ガードは入力ように拒否し、操作前にそのウィンドウ一つ（それだけ）を閉じる。

セキュリティの注意

このサーバーは、実際のマウスとキーボードのイベントを、動作中のデスクトップセッションに挿入し、そのスクリーンショットを撮る。 それが目的であり、リスクでもある。

• スクリーンショットは画面より何でも写し得る。whole_screen=true は全画面をキャプチャし、さらにそのまま暗号化されずにディスクへ書き出す。

• キーストロークは、フォーカスを持つウィンドウに送られる。ドライバは、VRoid Studio がフォーカスされたウィンドウである限り動作を拒否する。言い換えれば、侵害された・不用意なプロンプト命令でも、VRoid の内部をクリックできてしまう。

• vroid_launch(restart=true) は VRoid Studio を強制終了し、未保存の作業を失わせる。

• ここにあるものはサンドボックス化されておらず、確認ステップもない。

有人監視で実行する — 見ているセッションで走らせ、エージェントを無監視で運転させないこと。終了時は vroid_release() でデスクトップを返してあげる。

開発

uv run python scripts/smoke_test.py             # start the server, list tools, call vroid_status
uv run python scripts/smoke_test.py --screenshot # + one passive capture if VRoid is open
uv run vroid-driver shot                        # the original driver CLI, still here

vroid-driver（mcp_vroid.driver.cli）は、スパイクのシェル・インターフェイス — launch、shot、find、click、tab、slider、export、cam、apply-params、… — MCP クライアントを介さずにデバッグするのに便利。

クレジットとライセンス

ドライバー (src/mcp_vroid/driver/、native/) は、私の arrakis プロジェクトの中の tools/vroid-driver スパイクに始まり、MCP サーバーで包んだ形でここに同梱している。

MIT — LICENSE を参照。