Roblox-MCP

An MCP server that gives AI agents full control over Roblox Studio: launch/close Studio, open projects, execute arbitrary Luau, view and build scenes, write scripts, create GUI, configure lighting/camera, insert Toolbox assets, run Play Solo / Run playtests and read Output. Everything is undoable (Ctrl+Z).

How it works

AI agent (Claude / Cursor / any MCP client)
   │  MCP (stdio)
   ▼
roblox-mcp (Node.js) ── child_process ──► RobloxStudioBeta.exe (launch / open / close)
   │  HTTP localhost (127.0.0.1:8090)
   ▼
MCPBridge.luau plugin inside Roblox Studio (HttpService long-poll)
   └── executes commands through the regular Roblox API: Instance, Script.Source,
       Selection, RunService, InsertService (Toolbox), Lighting, Camera...

Why this shape: Studio plugins cannot accept inbound connections, but they can reach localhost via HttpService. So the plugin long-polls the bridge ("any commands?"), executes them, and posts results back via POST /result.

Related MCP server: Roblox Studio MCP Server

Features (50 tools)

Property values support Roblox types via encoding: {"__type":"Vector3","value":[10,5,0]}, Color3 (RGB 0–255), UDim2, CFrame (12 numbers), BrickColor ({"__type":"BrickColor","value":"Bright red"}), Enums ("Enum.Material.SmoothPlastic").

Quick start

1. Requirements

• Windows 10/11 (macOS partially supported: Studio CLI differs, bridge + plugin work the same)

• Node.js 18+

• Roblox Studio installed

• Any MCP client: Claude Desktop, Cursor, VS Code (Copilot / Cline), Windsurf…

2. Install the server

git clone https://github.com/<you>/Roblox-MCP.git
cd Roblox-MCP
npm install
npm run build

Smoke-test without Studio (the bridge should answer ok:true):

node scripts/test-bridge.mjs
node scripts/mcp-check.mjs   # full MCP roundtrip over stdio

3. Install the Studio plugin

1. Copy plugin/MCPBridge.luau into the plugins folder:

   • Windows: %LOCALAPPDATA%\Roblox\Plugins\MCPBridge.luau (create the folder if missing)

   • macOS: ~/Documents/Roblox/Plugins/MCPBridge.luau

2. Restart Roblox Studio and open any place.

3. On its first HTTP request Studio asks for localhost permission — allow it (or via Plugin Management → MCPBridge).

4. Output should show [MCP] Connected to bridge at http://127.0.0.1:8090.

5. (Optional, if ROBLOX_MCP_API_KEY is set) run in View → Command Bar:

   _G.MCP_SetApiKey("your-key-here")

4. Connect your AI client

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "roblox": {
      "command": "node",
      "args": ["C:/Users/<you>/Documents/Roblox-MCP/dist/index.js"],
      "env": { "ROBLOX_BRIDGE_PORT": "8090" }
    }
  }
}

Cursor / VS Code (mcp.json) — see examples/mcp.json.

Restart the client. The agent will see ~50 tools: studio_*, execute_luau, get_scene, …

Example prompts for the agent

• "Launch Studio and open C:\Games\MyObby.rbxl"

• "Show the Workspace structure, 2 levels deep"

• "Build an obby: 10 stair-step platforms + SpawnLocation + a score script"

• "Make a main menu: ScreenGui with Play and Shop buttons"

• "Insert Toolbox asset 12345678 into Workspace"

• "Run Play Solo for 5 seconds, show me the Output, then stop"

• "Find all scripts containing Damage and show the first match"

• "Set ClockTime 14, Brightness 3, push the fog further out"

Ready-made scenarios live in examples/:

• examples/obby.md — generating an obby from scratch

• examples/gui-menu.md — a main menu

• examples/debug-loop.md — the "run → read Output → fix" loop

Environment variables

No Studio exe yet (fresh install via the bootstrapper)? studio_launch starts RobloxStudioInstaller.exe automatically, waits for the real exe to appear, then opens your place.

Debugging without MCP (curl)

# bridge health
curl http://127.0.0.1:8090/health
# status (is the plugin connected?)
curl http://127.0.0.1:8090/status
# run one command synchronously (waits up to 30s for the plugin)
curl -X POST http://127.0.0.1:8090/command -H "Content-Type: application/json" -d '{"method":"get_workspace_info","params":{}}'

Troubleshooting

Security

• The bridge listens on 127.0.0.1 only, nothing is exposed to the network.

• An optional API key locks the bridge even from other local processes.

• execute_luau runs arbitrary code in Studio — only connect trusted MCP clients.

• All mutations go through ChangeHistoryService — Ctrl+Z undoes agent actions.

Repository layout

Roblox-MCP/
├── src/
│   ├── index.ts     # MCP stdio server
│   ├── bridge.ts    # HTTP bridge (long-poll) for the plugin
│   ├── studio.ts    # find/launch/close Studio, scan .rbxl files
│   └── tools.ts     # 50 MCP tools
├── plugin/
│   └── MCPBridge.luau  # Studio plugin (drop into the Plugins folder)
├── backrooms/       # example game: BACKROOMS Level 0 horror (Rojo project + built .rbxlx)
├── examples/        # mcp.json + prompt scenarios
├── scripts/         # smoke tests (bridge + full MCP roundtrip)
└── dist/            # build output (npm run build)

Roadmap

• Viewport screenshots via the plugin, returned to the agent as images

• Rojo sync (edit .lua files directly)

• Team Create / Open Cloud publishing (publish_place)

• .fbx/.obj model and audio imports

• WebSocket instead of long-poll for lower latency

• macOS/Linux CI, signed plugin installer

PRs and issues welcome.

License

MIT — see LICENSE.