roblox-studio-mcp

Roblox Studio MCP Bridge

Claude Code のような AI コーディングアシスタントを Roblox Studio に直接接続する Model Context Protocol（MCP） サーバーです。ターミナルから DataModel 内のインスタンスを読み取り、作成、変更、削除できます。

仕組み

Claude Code (MCP Client)
        |
   MCP Server (stdio)
        |
   HTTP Bridge (localhost:3001)
        |
   Studio Plugin (polls every 200ms)
        |
   Roblox Studio DataModel

ブリッジは次の 2 つの部分で構成されています。

1. MCP Server（TypeScript） — ローカルで実行され、stdio 経由で MCP の 14 個のツールを公開し、localhost:3001 で HTTP API を提供します
2. Studio Plugin（Luau） — HTTP API をポーリングしてコマンドを取得し、DataModel に対して実行して結果を返します

すべての書き込み操作は ChangeHistoryService でラップされるため、Studio で Ctrl+Z を押せば変更を元に戻せます。

利用可能なツール

ツール	種類	説明
get_descendants	読み取り	パスと任意の maxDepth を指定して、すべての子孫を取得します
get_children	読み取り	インスタンスの直下の子を取得します
get_properties	読み取り	インスタンスのシリアライズされたプロパティを取得します
find_instances	読み取り	className および／または namePattern で検索します
get_services	読み取り	すべての DataModel サービスを一覧表示します
get_selection	読み取り	Studio で現在選択されているインスタンスを取得します
create_instance	書き込み	プロパティを指定して新しい Instance を作成します
set_properties	書き込み	既存のインスタンスのプロパティを変更します
delete_instance	書き込み	インスタンスを破棄します（元に戻す操作に対応）
clone_instance	書き込み	インスタンスを複製し、新しい親に配置します
move_instance	書き込み	インスタンスの親を変更します
set_selection	書き込み	Studio の選択項目を設定します
insert_service	書き込み	game:GetService() 経由でサービスを挿入します
execute_luau	書き込み	プラグインのコンテキストで任意の Luau コードを実行します

パスには game から始まるドット表記を使います。例：game.Workspace.SpawnLocation。

前提条件

• Node.js 18+
• Roblox Studio
• Rojo 7+（aftman またはスタンドアロン版をインストール）

インストール

1. リポジトリをクローンする

git clone https://github.com/Justice219/roblox-studio-mcp.git
cd roblox-studio-mcp

2. 依存関係をインストールしてビルドする

npm install
npm run build

または、npm から直接インストールします。

npm install -g @jamesworkbenchcrm/roblox-studio-mcp

3. Studio プラグインをビルドしてインストールする

Rojo を使用する場合：

rojo build plugin.project.json -o MCPBridge.rbxmx

次に、プラグインファイルを Roblox のプラグインフォルダーにコピーします。

OS	パス
macOS	~/Documents/Roblox/Plugins/MCPBridge.rbxmx
Windows	%LOCALAPPDATA%\Roblox\Plugins\MCPBridge.rbxmx

または、プラグインフォルダーに直接ビルドします。

# macOS
rojo build plugin.project.json -o ~/Documents/Roblox/Plugins/MCPBridge.rbxmx

# Windows
rojo build plugin.project.json -o "%LOCALAPPDATA%\Roblox\Plugins\MCPBridge.rbxmx"

4. Studio で HttpService を有効にする

Roblox Studio を開き、次の設定を行います。

Home → Game Settings → Security → Allow HTTP Requests → ON

プラグインがローカルの MCP サーバーと通信するために必要です。

5. MCP クライアントを設定する

MCP クライアントの設定にサーバーを追加します。

Claude Code（~/.claude/settings.json）：

{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["/absolute/path/to/roblox-studio-mcp/dist/index.js"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["/absolute/path/to/roblox-studio-mcp/dist/index.js"]
    }
  }
}

/absolute/path/to/ を、リポジトリをクローンした実際のパスに置き換えてください。

6. Studio と MCP クライアントを再起動する

• Roblox Studio を再起動する（またはプラグインを再読み込みする）と、ツールバーに「MCP Bridge」ボタンが表示されます
• Claude Code／MCP クライアントを再起動します
• 接続されると、プラグインのステータスウィジェットに緑色の点が表示されます

使用方法

接続すると、AI アシスタントから Studio を直接操作できます。

"Create a Part named SpawnPad in Workspace at position 0, 5, 0"
"Get all children of ServerScriptService"
"Find all instances with className RemoteEvent"
"Set the BrickColor of game.Workspace.SpawnPad to Bright green"

アシスタントは MCP ツールを使って DataModel を読み取り、インスタンスを作成し、プロパティを設定するなどの操作を行います。これらはすべて、完全な取り消し機能に対応した状態で Studio にリアルタイムで反映されます。

設定

環境変数	デフォルト	説明
MCP_BRIDGE_PORT	3001	HTTP ブリッジのポート

MCP_BRIDGE_PORT=4000 npm start

開発

# Watch mode — recompiles on file changes
npm run dev

# Type-check without emitting
npm run typecheck

# Build
npm run build

# Start the server
npm start

アーキテクチャ

src/
├── index.ts           # Entry point — wires up all components
├── types.ts           # Interfaces, constants, command type definitions
├── mcp-server.ts      # MCP tool definitions (14 tools with Zod validation)
├── http-bridge.ts     # Express HTTP server (poll/result/heartbeat endpoints)
└── command-queue.ts   # In-memory command queue with timeout management

plugin/
├── init.server.luau   # Plugin entry point — polling loop, UI, toolbar
└── modules/
    ├── CommandRouter.luau  # Dispatches commands to handlers
    ├── HttpClient.luau     # HTTP requests to the bridge
    ├── PathResolver.luau   # Dot-notation path ↔ Instance resolution
    └── Serializer.luau     # Roblox type ↔ JSON serialization

セキュリティ

• HTTP ブリッジは 127.0.0.1 のみにバインド され、ネットワークに公開されることはありません
• 書き込み操作は、元に戻す操作に対応するため ChangeHistoryService でラップされます
• コマンドは 30 秒後にタイムアウトします
• 接続を維持するには 10 秒ごとのハートビートが必要です
• execute_luau はサンドボックスなしでプラグインのコンテキスト内のコードを実行するため、信頼できる入力にのみ使用してください

サポートされている Roblox の型

シリアライザーは、以下の型の双方向変換に対応しています。

Vector3 · Vector2 · CFrame · Color3 · BrickColor · UDim · UDim2 · Rect · NumberSequence · ColorSequence · NumberRange · Enum · Instance · Font · PhysicalProperties · Ray

すべての型は、情報を損なわずに往復変換できるよう、{ _type: "TypeName", ... } 形式の JSON を使用します。

トラブルシューティング

プラグインに赤い点が表示される／「切断」と表示される

• MCP サーバーが実行中であることを確認します（npm start）
• Studio で HttpService が有効になっていることを確認します
• ポートが一致していることを確認します（デフォルトは 3001）

Claude Code で「プラグインが接続されていません」というエラーが表示される

• Studio を開き、MCP Bridge のツールバーボタンが有効になっていることを確認します
• プラグインは読み込み時に自動起動します。プラグインを再読み込みしてみてください
• Studio の Output ウィンドウでエラーメッセージを確認します

ポートがすでに使用されています

• 別のインスタンスが実行中の可能性があります。終了するか、別のポートを使用してください。

  MCP_BRIDGE_PORT=4000 npm start
  

npm

npm install -g @jamesworkbenchcrm/roblox-studio-mcp

https://www.npmjs.com/package/@jamesworkbenchcrm/roblox-studio-mcp

ライセンス

MIT