Roblox Studio MCPをPythonから直接呼ぶ

Roblox Studio MCPをPythonから直接呼ぶ

Roblox Studio に内蔵された MCP サーバーを、MCP クライアントの設定を通さずに Python のスクリプトから呼んでみました。

サブプロセスとして起動し、標準入出力で JSON-RPC を 1 行ずつ送るだけで、Play の開始、Luau の実行、キー入力、画面の撮影までが動きました。

途中で 1 か所だけ大きくつまずいています。

公式が案内する mcp.bat 経由で起動すると initialize の応答が返らず、中にある StudioMCP.exe を直接起動すると返りました。

stdio の MCP サーバーは、決まった手順の JSON を改行区切りで送れば、どの言語からでも呼べます。

以下は、その手順と、自分で話してみて初めて見えた道具ごとの必須項目や待ち方の記録です。

前提(最小限)

Roblox Studio には MCP サーバーが組み込まれていて、Assistant の「…」から「Manage MCP Servers」を開き、「Enable Studio as MCP server」をオンにすると外から操作できるようになります。

公式の接続方法は、対応クライアントを選ぶだけの Quick connect、MCP の設定ファイルに書く JSON 設定、CLI のコマンドの 3 通りです。

Windows の JSON 設定と CLI のコマンドは、どちらも cmd.exe から %LOCALAPPDATA%\Roblox\mcp.bat を起動する形になっています。

サーバーは手元のマシンで動くプロセスで、クライアントとは stdio(標準入力と標準出力)でやり取りすると公式に書かれています。

公式の案内は Connect to the Roblox Studio MCP server(Roblox Creator Hub) にまとまっています。

ここではクライアントの設定は使わず、Python から stdio で直接話しました。

確かめた環境は Windows 11 と Studio 0.746 です。

MCP そのものの説明は次の記事に書いています。

MCPとは?AIエージェントと外部ツールをつなぐ標準規格

stdio の MCP は4つのメッセージで話せる

stdio の MCP で自分のスクリプトから StudioMCP.exe へ送る4つのメッセージの順番。1 initialize を送って応答を待ち、2 notifications/initialized、3 tools/list で道具の一覧を受け取り、4 tools/call で結果を受け取る。2025-11-25 までの版の手順。

stdio の MCP では、クライアントがサーバーをサブプロセスとして起動し、サーバーの標準入力に JSON-RPC を書き込み、標準出力から応答を読みます。

1 つのメッセージは 1 行で、メッセージの中に改行を含めてはいけない決まりです。

サーバーは標準出力に MCP のメッセージ以外を書かず、ログは標準エラーに出してよいことになっています。

この決まりは MCP 仕様 2025-11-25 の Transports の stdio の節に書かれています。

Transports - Model Context Protocol

話し始めの手順は次の 4 つです。

  1. initialize を送り、応答を待つ(id を付けたリクエスト)
  2. notifications/initialized を送る(id の無い通知)
  3. tools/list で道具の一覧を受け取る
  4. tools/call で道具を呼ぶ

仕様では、initialize の応答が来るまでは ping 以外のリクエストを送らないことになっています。

手順の細かい決まりは MCP 仕様 2025-11-25 の Lifecycle で確かめられます。

Lifecycle - Model Context Protocol

次のコードは、手元で動かしたスクリプトから送る部分だけを抜き出して縮めたものです。

# exe には Versions の下で見つけた StudioMCP.exe のパスを入れる(略)
proc = subprocess.Popen([exe], stdin=subprocess.PIPE, stdout=subprocess.PIPE, bufsize=0)

def send(method, params=None, rid=None):
    msg = {"jsonrpc": "2.0", "method": method}
    if params is not None:
        msg["params"] = params
    if rid is not None:
        msg["id"] = rid
    proc.stdin.write((json.dumps(msg) + "\n").encode())

send("initialize", {"protocolVersion": "2024-11-05", "capabilities": {},
                    "clientInfo": {"name": "script", "version": "1"}}, 1)
# id 1 の応答を stdout から 1 行ずつ読んで待つ(略)
send("notifications/initialized")
send("tools/list", {}, 2)
# 応答は stdout に 1 行ずつ。id で対応を取る

私が送った protocolVersion は 2024-11-05 で、Studio のサーバーはこれで initialize に応答しました。

道具を呼ぶときは、tools/call の params に道具の名前を name、引数を arguments として入れます。

道具の一覧には、それぞれの引数の形を表す inputSchema が付いてくるので、必須の項目はそこで確かめられます。

仕様の新しい版 2026-07-28 では、この initialize の手順そのものが無くなりました。

新しい版では、毎回のリクエストの _meta に版と機能を載せ、サーバーは対応する版を返す server/discover を持つ形に変わっています。

古い版と新しい版の両方に対応するサーバーは initialize にも応答できますが、新しい版だけのサーバーには上の手順は通りません。

変更点は MCP 仕様 2026-07-28 の Key Changes に並んでいます。

Key Changes - Model Context Protocol

自前で話すときは、相手のサーバーがどちらの版で話すのかを最初に確かめておくと迷いません。

Studio のサーバーに繋ぐ最小の手順

実行ファイルは %LOCALAPPDATA%\Roblox\Versions\<版>\StudioMCP.exe にありました。

Studio は自動で更新され、そのたびに版のフォルダが変わるので、パスは固定で書かずに Versions の下を探して見つける形にしています。

tools/list の応答を受け取ってから、8 秒待って tools/call を送りました。

待たずに呼んだときに、No Roblox Studio instances are connected で失敗したことがあるためです。

エラーの文面どおり、サーバーのプロセスは動いていても、Studio がまだ繋がっていない状態だったと読めます。

待つ時間の下限は測っていないので、8 秒は私が使った値でしかありません。

list_roblox_studios を呼ぶと、開いている Studio の id と名前が返ってきます。

Studio を 2 つ開いた状態でも、studio_id で片方を指定して操作できました。

公式にも、どの道具も studio_id で操作する Studio を指定すると書かれています。

mcp.bat で initialize が返らないとき

同じスクリプトで、起動するコマンドだけを cmd.exe /c mcp.bat に替えると、initialize の応答が 45 秒待っても返りませんでした。

2 回試して、2 回とも同じでした。

StudioMCP.exe を直接起動すると、同じ initialize に応答が返りました。

mcp.bat を通すと返らない原因は確かめていません。

公式の JSON 設定は mcp.bat を使う形なので、クライアントの設定どおりにしても繋がらないときは、この切り分けが手がかりになるでしょう。

ラッパーのバッチで止まったら、中の実行ファイルを直接起動して同じメッセージを送ると、止まっているのがラッパーかサーバーかを分けられます。

直接起動で応答が返れば、サーバーとメッセージの形は問題なく、間に挟まった起動の層を疑えます。

直接起動でも返らなければ、メッセージの形か、Studio 側の設定を先に見直すことになります。

道具ごとのつまずき

クライアント経由では AI が引数を組み立ててくれるので、必須の項目や待ち方は表に出てきません。

自分で引数を書いたことで、次のような点に気づきました。

MCP の道具の説明が、呼ぶ側の選び方にどう効くかは次の記事にまとめています。

MCPツールのdescriptionの書き方|選び間違い対策

execute_luau

Luau のコードを実行する道具で、datamodel_type に Edit・Server・Client のどれかを入れるのが必須です。

Luau の return で返した値は、文字として返ってきます。

大きな JSON を返させたときは、100,000 文字のあたりで切れて JSON として壊れていました。

そのときは返す中身を小さく分け、何回かに分けて取り直しています。

MCP を通さずに Studio をコマンドラインから起動して Luau を走らせ、動く床の挙動を数字で測った記録は、別の記事に書きました。

Roblox の動く床|乗っても運ばれない原因を4方式で実測

start_stop_play と get_studio_state

Play の開始と停止は start_stop_play で、引数の is_start で開始か停止かを指定します。

get_studio_state を呼ぶと、いま使える datamodel が分かります。

Play 中は Client と Server の 2 つが返ってきました。

user_keyboard_input

キー入力を送る道具も、datamodel_type を省くと datamodel_type is required で失敗します。

キーを押して、待って、離すまでを、actions に順に入れて 1 回の呼び出しで送りました。

wait の wait_time_ms は 0〜10000 の範囲で指定します。

次の引数で、Play 中のキャラクターが歩きました。

{"studio_id": "...", "datamodel_type": "Client", "actions": [
  {"action": "keyDown", "key_code": "W"},
  {"action": "wait", "wait_time_ms": 2000},
  {"action": "keyUp", "key_code": "W"}
]}

studio_id には list_roblox_studios で得た id を入れます。

screen_capture

画面を撮る道具で、camera_position と look_at_position を渡すと、カメラの位置と見る先を指定して撮れます。

結果の content のうち type が image のものに、base64 の画像が入っています。

カメラを動かした直後の 1 枚では、壁の SurfaceGui の絵が写っていませんでした。

同じ位置で撮り直すと写ったので、写っていないときは 1 枚目だけで判断せずに撮り直してみる価値があります。

これは 1 回だけの観察で、原因は確かめていません。

最後に

stdio の MCP サーバーは、initialize、initialized、tools/list、tools/call の 4 つを改行区切りの JSON で送れば、クライアントが無くても自分のスクリプトから呼べました。

ただしこれは 2025-11-25 までの版の手順で、2026-07-28 の版からは initialize が無くなっているので、相手のサーバーがどちらで話すのかを先に確かめる必要があります。

自分で話すと、クライアントが隠している必須の引数や、接続が整うまでの待ちが見えてきます。

設定どおりに繋がらないときは、ラッパーを外して実行ファイルを直接起動するところから切り分けると、原因の場所を狭められます。

以上です。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA