Studio Sidecar

Studio Sidecar — Roblox Studio 用のコンパニオン MCP サーバー

English | 繁體中文

Studio Sidecar は Roblox Studio 組み込みの MCP サーバーでは補えない部分を埋めます。置き換えるものではありません。

2026 年以降、Roblox Studio には独自の MCP サーバー（Studio とともにインストールされる StudioMCP、stdio トランスポート）が付属しており、スタンドアロンの Roblox/studio-rust-mcp-server リポジトリはアーカイブされています。組み込みサーバーには、サードパーティーが再実装できないツールがあります。generate_mesh、generate_material、generate_procedural_model はモデレーション機能を備えた Roblox のクラウド AI を使用し、search_asset、insert_asset、upload_image はサインイン中のアカウントのインベントリ権限を使用します。また、user_keyboard_input と user_mouse_input は CreateVirtualInput を経由します。組み込みサーバーを置き換えると、これらすべてが失われてしまいます。

そこで Studio Sidecar は、組み込みサーバーの構造上できないことだけを追加し、それ以外は組み込みサーバーに任せます。

• まだ開いていないプレースを開き、マシン上のすべての Studio プロセスと StudioMCP ブローカー／スタブを確認できます。
• PlaceId で書き込みを保護し、実行時エラーを読みやすい値として返して出力を切り捨てずに Luau を実行できます。また、バイト単位で完全に検証しながら、出力上限 100k を超えるスクリプトを抽出できます。
• Roblox Open Cloud 経由でアセットをアップロード、更新、アーカイブできます。更新が気づかれないまま重複排除された場合は、明示的に判定結果を示します。

Studio プラグインは不要です。ツールは 11 個です。Windows では完全に検証済みで、macOS では一部検証済みです（プラットフォームのサポートを参照）。

目次

• ツール
• クイックスタート
• 設定
• 組み込みサーバーが伝えないツールの情報
• プラットフォームのサポート
• 制約
• 開発
• ライセンスと商標

ツール

ツール	組み込みサーバーでは実行できない理由
roblox_get_status	Open Cloud が設定されているか、またアップロードで読み取り可能なフォルダーを表示します
roblox_list_studios	組み込みサーバーは 1 つの Studio プロセス内で動作するため、ほかの Studio プロセスや StudioMCP のブローカー／スタブ構造を確認できません
roblox_open_place	まだ開いていないプレースを開くには、新しい別プロセスが必要なため、オペレーティングシステム側の処理が必要です
roblox_cleanup_stubs	同じ理由です。デフォルトでは状態を報告し、apply=true の場合にのみスタブを終了します。ブローカーは終了しません
roblox_place_guard	組み込みの multi_edit はパスを指定して書き込みます。誤った studio_id を指定すると、取り消しも警告もなく別のゲームを上書きしてしまいます
roblox_luau_safe	組み込みの execute_luau には PlaceId のチェックがなく、出力が 100k 文字を超えると警告なしに切り捨てられます
roblox_extract_place	100k の切り捨て境界に対応するツールはありません。チャンク分割、センチネル、ファイルごとのバイトチェックは呼び出し側に委ねられており、誤ってもエラーにはなりません
roblox_get_asset	組み込みの search_asset は保有者を creatorId として報告し、作成者は報告しません
roblox_upload_asset	Studio 内の AssetService:CreateAssetAsync は、現在常に not available yet をスローします
roblox_update_asset	CreateAssetVersionAsync も同様に利用できません
roblox_archive_asset	組み込みサーバーには Open Cloud のインターフェースがありません

意図的に含めていないもの：スクリプトの読み取りと書き込み、シーンのクエリ、execute_luau、screen_capture、プレイテスト。これらは組み込みサーバーにすでに備わっているため、別の実装を加えても乖離するだけです。

Studio 側で Luau が実行される仕組み

MCP プロセスは、サーバーとクライアントを同時に担うことができます。Studio Sidecar は StudioMCP を独立した子プロセスとして起動し、MCP クライアントとして接続します。これにより、組み込みの execute_luau を利用できます。チャンク分割、センチネル、バイトチェックの仕組みは、単一のツールにまとめられています。クライアントを正常に閉じると子プロセスも終了するため、この方法ではスタブが残りません。

StudioMCP の起動には、Studio Sidecar は Roblox のセットアップガイドと同じランチャーを使用します。Windows では %LOCALAPPDATA%\Roblox\mcp.bat を cmd.exe /c 経由で実行します。mcp.bat がない場合は、%LOCALAPPDATA%\Roblox\Versions\ にある更新日時が最も新しい StudioMCP.exe にフォールバックします。macOS では、/Applications または ~/Applications にある RobloxStudio.app 内の StudioMCP を使用します。

クイックスタート

要件：Enable Studio as MCP server を有効にした Roblox Studio（Studio で Assistant → … → Manage MCP Servers）、および Node.js 22 以降。

AI クライアントに Studio Sidecar を登録します。Claude Code：

claude mcp add studio-sidecar --scope user \
  -e ROBLOX_API_KEY="<your Open Cloud API key>" \
  -e ROBLOX_CREATOR_USER_ID="<your Roblox user ID>" \
  -e ROBLOX_UPLOAD_ROOT="<folder that uploads may read from>" \
  -- npx -y @gjlmotea/studio-sidecar-mcp

mcpServers JSON 設定を読み込むクライアント（Claude Desktop、Cursor、Gemini CLI）：

{
  "mcpServers": {
    "studio-sidecar": {
      "command": "npx",
      "args": ["-y", "@gjlmotea/studio-sidecar-mcp"],
      "env": {
        "ROBLOX_API_KEY": "<your Open Cloud API key>",
        "ROBLOX_CREATOR_USER_ID": "<your Roblox user ID>",
        "ROBLOX_UPLOAD_ROOT": "<folder that uploads may read from>"
      }
    }
  }
}

VS Code では代わりにトップレベルの servers キーを使用し、各サーバーに type を指定します。入力変数を使うことで、キーをファイルに記載せずに済みます。VS Code はサーバーの初回起動時にキーの入力を求め、安全に保存します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "roblox-api-key",
      "description": "Roblox Open Cloud API key",
      "password": true
    }
  ],
  "servers": {
    "studio-sidecar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@gjlmotea/studio-sidecar-mcp"],
      "env": {
        "ROBLOX_API_KEY": "${input:roblox-api-key}",
        "ROBLOX_CREATOR_USER_ID": "<your Roblox user ID>",
        "ROBLOX_UPLOAD_ROOT": "<folder that uploads may read from>"
      }
    }
  }
}

各クライアントでの設定ファイルの場所：

クライアント	設定ファイル
Claude Desktop	macOS：~/Library/Application Support/Claude/claude_desktop_config.json、Windows：%APPDATA%\Claude\claude_desktop_config.json。Settings → Developer → Edit Config から開けます
Cursor	すべてのプロジェクトに適用する場合は ~/.cursor/mcp.json、1 つのプロジェクト内で使う場合は .cursor/mcp.json
Gemini CLI	~/.gemini/settings.json（ユーザー）、.gemini/settings.json（プロジェクト）
VS Code	ワークスペース内の .vscode/mcp.json、または MCP: Open User Configuration コマンドで開くユーザー用 mcp.json

参照元：Claude Desktop、Cursor、Gemini CLI、VS Code。

3 つの変数はいずれも省略可能です。キーがない場合、4 つの Open Cloud ツールは実行を拒否します。ROBLOX_UPLOAD_ROOT がない場合、すべてのアップロードが拒否されます。それ以外のツールは通常どおり動作します。バージョン管理の対象となる設定ファイルには、キーを記載しないでください。

Studio に組み込まれている MCP サーバーも登録してください。スクリプト編集、スクリーンショット、プレイテストはそちらで行います。各プラットフォームでの起動コマンド（macOS では StudioMCP、Windows では cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat）は、Roblox のセットアップガイドに記載されています。

macOS：

claude mcp add roblox-studio --scope user -- /Applications/RobloxStudio.app/Contents/MacOS/StudioMCP

Windows：

claude mcp add roblox-studio --scope user -- cmd.exe /c "%LOCALAPPDATA%\Roblox\mcp.bat"

JSON 設定では、macOS のエントリは "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"、Windows のエントリは "command": "cmd.exe" と "args": ["/c", "%LOCALAPPDATA%\\Roblox\\mcp.bat"] です。Windows では StudioMCP.exe ではなく mcp.bat を登録してください。mcp.bat のパスは変わりませんが、StudioMCP.exe は %LOCALAPPDATA%\Roblox\Versions\version-<hash>\ にあり、このフォルダーは Studio のアップデートに伴って変わります。

登録後にセッションを再起動し、roblox_get_status を呼び出して openCloudConfigured と allowedUploadRoots を確認します。

Finder やスタートメニューから起動したデスクトップアプリでは、シェルの PATH が認識されないことがよくあります。サーバーが起動しない場合は、npx の絶対パスを使用してください（ソースから実行する場合は node の絶対パスを使用してください）。

ソースから実行する

git clone https://github.com/gjlmotea/studio-sidecar-mcp.git
cd studio-sidecar-mcp
corepack pnpm install --frozen-lockfile
corepack pnpm run build
claude mcp add studio-sidecar --scope user -- "$(which node)" "$PWD/dist/index.js"

上記のように絶対パスで登録してください。プロジェクトフォルダーを指定する手書きの .mcp.json は使用しないでください。Claude Code は CLAUDE_PROJECT_DIR を自身の環境ではなくサーバーの環境に設定するため、.mcp.json エントリ、または ~/.claude.json のローカルスコープもしくはユーザースコープのエントリの command や args に ${CLAUDE_PROJECT_DIR} を指定する場合は、${CLAUDE_PROJECT_DIR:-.} のようなデフォルト値が必要です。デフォルト値がない場合もエントリは読み込まれますが、claude mcp list に変数が見つからないという警告が表示され、展開されていない ${CLAUDE_PROJECT_DIR} の文字列がそのまま使用されます。.mcp.json のプロジェクトスコープサーバーにも承認が必要です。対話型セッションでは使用前に確認されますが、claude -p の実行、Agent SDK セッション、クラウドセッションでは確認なしで読み込まれます。Claude Code MCP documentation を参照してください。

設定

変数	用途
ROBLOX_API_KEY	アセットの読み取りと書き込みが可能な Open Cloud API キー（Creator Dashboard → Open Cloud API Keys）
ROBLOX_CREATOR_USER_ID	アップロード時に creationContext に記録されるクリエイター
ROBLOX_UPLOAD_ROOT	アップロード元として読み取り可能なフォルダー。複数指定でき、プラットフォームのパス区切り文字で連結します。Windows では ;（C:\assets\models;D:\decals）、macOS では :（/Users/you/models:/Volumes/art/decals）です。未設定の場合、すべてのアップロードが拒否されます
ROBLOX_STUDIO_PATH	Studio の実行ファイル。未設定の場合、現在のインストールから自動的に解決されます

ROBLOX_UPLOAD_ROOT は意図的なガードレールです。アップロードではローカルファイルが外部サービスに送信され、Models のアップロードは取り消せないため、MCP クライアントが任意のファイルパスを選べないようにする必要があります。比較の前に、ファイルと許可されたフォルダーの両方を realpath で解決するため、許可されたフォルダー内のシンボリックリンクを使ってアップロード先を別の場所にすることはできません。ファイルは一度だけ開かれ、開いたハンドルを通じて再確認されます（引き続き許可されたフォルダー内にあり、同じファイルであること）。送信するバイト列もそのハンドルから読み取るため、確認後にパスを差し替えても影響はありません。ハードリンクが複数あるファイルは拒否されます。許可されたフォルダー内のハードリンクが、同じボリューム上の別の場所にあるファイルを指す可能性があるためです。代わりにコピーをアップロードしてください。

組み込みサーバーが伝えない、ツールが把握していること

以下はすべて実機で確認され、回帰テストが用意されています。

起動インテントの引用符処理は、失敗しても通知されません。 Studio は -launchIntentString "{\"task\":\"EditPlace\",\"universeid\":\"…\",\"placeid\":\"…\"}" を想定しています。エスケープされていない引用符は Windows のコマンドラインパーサーに取り除かれ、Studio は壊れた JSON を受け取ります。インテントを無視してエラーなしで空のセッションを開くため、手掛かりはウィンドウタイトルが <place name> - Roblox Studio ではなく Roblox Studio になることだけです。Studio Sidecar は引数を配列として spawn に渡し、CommandLineToArgvW のルールをテスト可能にします。universeid は scene/place.json の gameId です。

ウィンドウにフォーカスを奪わせないでください。 SetForegroundWindow の 2 秒後、Studio で誤ってキーを押したところ、読み込まれたばかりのプレースが閉じてしまいました。roblox_open_place はブローカーへの接続とプロセスのタイトルのみをポーリングします。

ブローカーを終了してはいけません。また、その識別対象は移り変わります。 StudioMCP は 1 つのブローカーとクライアントごとのスタブで構成されます。最初のブローカーは 127.0.0.1:13469 で待ち受け、Studio 自身とすべてのスタブがそこに接続します。ブローカーを終了すると、Studio の接続も含め、すべての接続が切断されます。また、ブローカーの役割は時間とともに別のプロセスへ移るため、ブローカーは記憶しておいた PID ではなく、常に「13469 で待ち受けているプロセス」として識別します。roblox_cleanup_stubs はブローカーを識別できない場合、処理を中止します。一部のクライアントが終了時にスタブを回収しないため（openai/codex#25893 を参照）、まだ稼働中の可能性があるセッションに影響しないよう、経過時間のしきい値を設けています。 更新の成功は HTTP ステータスではなく、revisionId で判断します。 バイト単位で同一のコンテンツを持つアセットに PATCH を行うと、エラーなしで HTTP 200 と done: true が返されますが、revisionId は変化しません。これはコンテンツが重複排除されたためです。roblox_update_asset は更新前後の revisionId を比較し、updated、deduplicated、または indeterminate を報告します。revisionId が増加しても、Studio に新しいコンテンツが表示されるとは限りません。Studio 側のキャッシュは、Open Cloud で確認できる範囲外です。コンテンツを置き換えるには、updateMask を指定しないでください（updateMask=fileContent は Unknown field file_content で失敗します）。これはメタデータの変更にのみ使用します。

100k の切り詰めは StudioMCP 自体に起因します。 StudioMCP に直接送信して測定したところ、100,000 文字の返信は完全な状態で届きますが、120,000 文字の返信は 100,015 文字で途切れ、末尾は ... (truncated) になります。これを解消できるクライアントはありません。そのため、roblox_extract_place では次の 3 つの保護策をすべて使用します。

1. 各チャンクの末尾にセンチネルを付けます。センチネルのないチャンクは不完全と見なされます。長さだけでは、完全な返信と切り詰められた返信を判別できません。
2. UTF-8 に対応した切り出し位置は Lua で決定して報告し、呼び出し側はそこから続けます。そのため、双方が別々に境界を計算することはありません。
3. ファイルごとにバイト数を確認します（String.length ではなく Buffer.byteLength を使用）。不一致があれば、全抽出を中止します。部分的に正しいスナップショットは成功したように見えるためです。

各呼び出しは、専用のキー shared.RBXEXTRACT_<32 hex digits>（Lua VM のメモリ内のみで使用し、DataModel や .rbxl には保存しません）の下にデータを一時保存し、その後消去します。そのため、同時に実行される呼び出しが互いのデータを読み取ることはありません。消去に失敗した場合、同じ Studio に到達する次の呼び出しで再度消去します。試行は合計 3 回までです。各キーには最終使用時刻も記録され、新しいキーを作成する際には、15 分間アイドル状態のキーをすべて消去します。そのため、解放の失敗、シャットダウン、クラッシュで残されたキーも、その Studio への次の呼び出しで削除されます。シャットダウン中、サーバーがクリーンアップのためだけに Studio に再接続することはありません。

インスタンス名には ..、パス区切り文字、CON や NUL などの Windows デバイス名を含め、ほぼどのようなものでも指定できるため、すべてのパスセグメントをサニタイズします。デバイス名には、すべてのプラットフォームで末尾に _ を付けます（CON は CON_.server.luau になります）。これにより、macOS で作成したスナップショットも Windows で開けます。また、書き込み前に最終パスが出力フォルダー内にあることを確認します。

新しいスナップショット全体は、まず抽出処理によって出力フォルダー内に作成された新しいフォルダー（.studio-sidecar-staging-<random>）に書き込まれます。すべてのファイルが揃ってから切り替えを開始します。以前のスナップショットのファイルを退避し、新しいファイルを、名前がすでに使われている場合は失敗するハードリンクで配置します（ハードリンクに対応していないファイルシステムでは、排他的作成を使用します）。切り替え中に問題が発生した場合、新しいファイルを削除して以前のスナップショットを元に戻すため、実行に失敗しても以前のスナップショットはそのまま残ります。同じフォルダーへの抽出は順番に実行されます。途中で強制終了された実行では、.studio-sidecar-staging-* フォルダーが残ることがあります。このフォルダーにはスナップショットファイルのみが含まれるため、安全に削除できます。

既存のファイルが上書きされることはありません。ファイルシステムが同一と見なす名前（大文字と小文字を区別しないボリューム上の Σ、ς、σ など）も含め、名前がすでに使われている場合、スクリプトは次の ~n サフィックスを付けます。実際に書き込まれたパスは scene/scripts.json に記録されます。同じフォルダーに再実行する場合、そのフォルダーにある以前の scene/scripts.json に記載されたファイルのみが置き換えられます。scene/ 内のファイルが Studio Sidecar によって書き込まれたものではないフォルダーは、処理を拒否します。そのようなファイルのいずれかがハードリンクに変わっている場合、削除されるのはその名前だけで、もう一方の名前にあるコンテンツはそのまま残ります。 Studio ブリッジはサーバーと同じ期間、存続させる必要があります。 呼び出しごとに閉じると、最初の呼び出しは成功しますが、それ以降はすべて「Unable to reach Roblox Studio right now」で失敗し、Studio が閉じているように聞こえます。実際は違います。ブリッジを閉じるとスタブが終了し、次の呼び出しがブローカーと競合します。同じメッセージは、新しいスタブがブローカーに到達する前のコールドスタート時にも表示されます。そのためブリッジは、そのメッセージが表示された場合に限り、Studio の一覧取得を最大 20 秒間再試行します。待ち時間は試行ごとに 250 ms ずつ延び、最大 1.5 秒になります。サーバーのシャットダウンが始まると、ブリッジは新しい接続を拒否するため、まだ完了していない呼び出しから新しいスタブを起動することはできません。

Open Cloud の形式は限定されています。 モデルで受け付けるのは .fbx のみです。デカールで受け付けるのは bmp、jpeg、png、tga です。音声で受け付けるのは mp3 と ogg で、月間クォータの制限があり、新規作成のみ可能で更新はできません。形式が正しくない場合、操作のポーリング後に初めて失敗します。そのため、ローカルで拒否します。モデルとデカールではアーカイブがサポートされたことはなく、roblox_archive_asset はその旨を事前に通知します。

プラットフォームのサポート

	Windows	macOS
指定したプレースを開く	✅ 検証済み	✅ 実装済み、実機では未検証
プロセスとブローカーの検査	✅ 検証済み（PowerShell）	✅ 検証済み（ps + lsof）
スタブのクリーンアップ	✅ 検証済み	✅ 実装済み、実機では未検証
ウィンドウタイトル	✅	❌ 常に undefined（アクセシビリティの許可が必要）
Open Cloud ツール	✅	✅（通常の HTTP）

プラットフォームごとの差異は ports/process-inspector.ts の背後にあります。ブローカーの検出、スタブの分類、クリーンアップは共通です。Linux では Roblox Studio が動作せず、空の応答は「Studio が実行されていない」と解釈されるため、空のスナップショットを返すのではなく、明示的に拒否します。

境界

• ウィンドウのフォーカスは変更しません。 フォーカスを奪うと、誤って押されたキーによって、読み込み直後のプレースが閉じられる可能性があります。
• roblox_luau_safe は、任意のコードを実行する新しい方法ではありません。 execute_luau はすでにクライアントが利用できます。このツールは、同じエントリポイントの前段に必須の PlaceId ガード、チャンク全体を囲む 1 つの pcall、分割された結果を追加します。pcall は実行時エラーを捕捉し、読み取り可能な値として返します。エラーの後にあるコードは実行されず、エラー前に行われた変更もロールバックされません。これはサンドボックスではありません。
• 13469 上のブローカーの非公開プロトコルをリバースエンジニアリングしません。 通常の MCP クライアントとして StudioMCP と通信すれば、その必要はありません。
• 「インベントリから削除」は行いません。 この処理には、サインイン済みセッションの Cookie と CSRF トークンを使った inventory.roblox.com 経由の操作が必要ですが、Open Cloud API キーでは実行できません。
• 既知の制限：出力フォルダーにすでに存在するフォルダーは、切り替え中に置き換えられる可能性があります。 ファイルは新しいステージングフォルダーに書き込まれますが、配置時には出力フォルダー内の既存のサブフォルダーをパスに沿ってたどります。各階層は realpath で解決され、先に出力フォルダー内にあることを確認します。それでも、同じマシン上の別のプログラムが確認後、移動前にフォルダーをシンボリックリンクに置き換える可能性があります（確認と使用の間の競合）。移動で作成されるのは常に新しい名前だけなので、最悪の場合でも出力フォルダーの外に新しいファイルが 1 つ現れるだけです。出力フォルダー外のものが上書きされたり削除されたりすることはありません。
• 既知の制限：解放されなかったバッファは、次の呼び出しまで残ります。 解放できなかった Luau バッファは、後続の呼び出しが同じ Studio に到達するまで（また、アイドル時の一括処理については、15 分間アイドル状態になるまで）、または Studio が閉じるまで、Studio の shared テーブルに残ります。

開発

corepack pnpm install
corepack pnpm run verify          # typecheck, tests, build, stdio smoke
corepack pnpm run verify:live     # read-only checks against real Studio and a real account
corepack pnpm run verify:extract  # end to end: open_place → place_guard → luau_safe → extract_place

verify:live は読み取り専用の操作のみを実行します。アップロード、更新、場所を開く操作、プロセスの終了は行いません。Open Cloud の部分には ROBLOX_API_KEY とアセット ID（node scripts/verify-live.mjs <assetId>）が必要で、どちらかがない場合はスキップされます。

verify:extract には ROBLOX_VERIFY_PLACE_ID、ROBLOX_VERIFY_UNIVERSE_ID（所有している場所）、および ROBLOX_VERIFY_BASELINE（手作業で作成し、バイト単位で検証したスクリプトのスナップショット）が必要です。Studio のインスタンスを開き、抽出したスクリプトとスナップショットをバイト単位で比較します。ブリッジのライフタイムに関するバグは複数のツール呼び出しを連続して行った場合にのみ発生するため、手順は意図的に連続して実行されるようになっています。

ライセンスと商標

MIT。

Studio Sidecar は独立したオープンソースプロジェクトであり、Roblox Corporation とは提携しておらず、同社から承認を受けてもいません。Roblox、Roblox Studio、および Luau は Roblox Corporation の商標です。