Roblox-MCP
Provides full control over Roblox Studio, including launching/closing Studio, opening places, executing arbitrary Luau, inspecting and building scenes, managing scripts, creating GUI, configuring lighting and camera, inserting Toolbox assets, running Play Solo/Run playtests, and reading Output. All mutations are undoable via ChangeHistoryService.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Roblox-MCP build a simple obby with 10 platforms and a spawn point"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Features (50 tools)
Group | Tools |
Studio |
|
Bridge |
|
Full access |
|
Scene |
|
Scripts |
|
Playtesting |
|
Toolbox |
|
GUI / world |
|
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 buildSmoke-test without Studio (the bridge should answer ok:true):
node scripts/test-bridge.mjs
node scripts/mcp-check.mjs # full MCP roundtrip over stdio3. Install the Studio plugin
Copy
plugin/MCPBridge.luauinto the plugins folder:Windows:
%LOCALAPPDATA%\Roblox\Plugins\MCPBridge.luau(create the folder if missing)macOS:
~/Documents/Roblox/Plugins/MCPBridge.luau
Restart Roblox Studio and open any place.
On its first HTTP request Studio asks for localhost permission — allow it (or via Plugin Management → MCPBridge).
Output should show
[MCP] Connected to bridge at http://127.0.0.1:8090.(Optional, if
ROBLOX_MCP_API_KEYis 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
Damageand 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 scratchexamples/gui-menu.md— a main menuexamples/debug-loop.md— the "run → read Output → fix" loop
Environment variables
Variable | Purpose | Default |
| bridge start port (probes +0…+9 on conflict) |
|
| key for | (empty — no auth, localhost only) |
| plugin wait timeout |
|
| path to | (auto) |
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
Symptom | Fix |
| Open Studio with any place, check |
Plugin can't find the bridge | Start the MCP server first ( |
Studio asks for HTTP permission | Allow localhost for the plugin (Plugin Management). Without it the plugin can't reach the bridge |
| Install Studio or set |
| Asset is private/off-sale or no access. Public free models insert fine |
| This Studio version has no scriptable Save API — press Ctrl+S. Everything else works |
Security
The bridge listens on
127.0.0.1only, nothing is exposed to the network.An optional API key locks the bridge even from other local processes.
execute_luauruns 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
.luafiles directly)Team Create / Open Cloud publishing (
publish_place).fbx/.objmodel and audio importsWebSocket instead of long-poll for lower latency
macOS/Linux CI, signed plugin installer
PRs and issues welcome.
License
MIT — see LICENSE.
Available Tools
50 toolsbridge_statusB
Check HTTP bridge status and whether the Studio plugin is connected.
Inputs: no named parameters.
bulk_createA
Create MANY instances in ONE call (one undo step, one roundtrip). Each item: {className, name?, parent?, properties?}. Building a whole room in a single call.
Inputs: items (required).
clear_outputB
Clear the plugin-captured output buffer.
Inputs: no named parameters.
create_guiB
Build GUI quickly: creates ScreenGui (in StarterGui) with nested elements (Frame/TextButton/TextLabel/ImageLabel...). Each child: {className, name, properties, children}.
Inputs: name (required), parent, children, properties.
create_instanceB
Create any Instance (Part, Model, Folder, PointLight, SelectionBox, etc.) with optional parent, name and properties. Values support Roblox types via {__type:'Vector3'|'Color3'|'UDim2'|'CFrame'|'BrickColor', value:...} or plain JSON.
Inputs: className (required), name, parent, properties.
create_scriptC
Create a new Script/LocalScript/ModuleScript with source code.
Inputs: name (required), parent (required), scriptType (required), source.
delete_instanceC
Delete an instance by path.
Inputs: path (required).
delete_scriptC
Delete a script by path.
Inputs: path (required).
duplicate_instanceC
Duplicate (clone) an instance, optionally with a new name.
Inputs: path (required), newName.
execute_luauA
Execute arbitrary Luau code inside Roblox Studio (Command-Bar equivalent, with undo support). Return value / prints are captured. This unlocks EVERYTHING: Toolbox, tools, services, physics, etc. Multi-line allowed.
Inputs: code (required), timeoutMs.
find_instancesA
Search the whole game by name and/or class: 'all Scripts with Boss in the name'. Faster than dumping the full scene.
Inputs: root, limit, className, nameContains.
get_cameraA
Get current Studio camera (CFrame components, Focus, FieldOfView).
Inputs: no named parameters.
get_childrenB
List direct children of one instance (shallow: Name/ClassName/Path).
Inputs: path (required).
get_instanceB
Get properties of one instance by dotted path (e.g. 'Workspace.SpawnLocation').
Inputs: path (required).
get_lightingA
Get key Lighting properties (ClockTime, Brightness, Ambient, etc.).
Inputs: no named parameters.
get_outputC
Get recent Studio Output log lines captured by the plugin.
Inputs: limit.
get_performanceA
Read live Studio performance stats (FPS, frame time, physics, contacts, memory). Diagnose 'weak laptop' vs real bugs.
Inputs: no named parameters.
get_play_stateA
Get current playtest state (isPlaying, isRunning, mode).
Inputs: no named parameters.
get_sceneA
List scene tree (descendants) from a root with ClassName/Name/Path. Use for viewing the scene, finding GUI, checking builds.
Inputs: root, maxDepth, maxNodes, includeProperties.
get_selectionB
Get current Studio selection (paths).
Inputs: no named parameters.
get_workspace_infoA
Get Workspace stats: child count, part count, gravity, streaming, place name.
Inputs: no named parameters.
grep_scriptsC
Search script sources for a Lua pattern / substring.
Inputs: pattern (required), root.
insert_assetC
Insert a Toolbox/model asset by numeric asset ID into the game (InsertService:LoadAsset). E.g. free models, meshes.
Inputs: assetId (required), parent.
kill_playerA
Kill a playtest character (tests death screens, respawn, Entity kills).
Inputs: player.
list_scriptsB
List all Script/LocalScript/ModuleScript under a root (default game).
Inputs: root.
play_soloA
Start Play Solo playtest (F5). Agent can then check behavior via get_output / get_play_state / execute_luau.
Inputs: no named parameters.
playtestA
FULL playtest in ONE call: starts Play Solo (or Run), waits N seconds, captures Output + play state, stops, returns the report. The core of the agent debug loop.
Inputs: mode, seconds, outputLimit.
read_scriptB
Read Source of a script by path (e.g. 'ServerScriptService.MyScript', 'Workspace.Part.Script').
Inputs: path (required).
redoB
Redo last undone Studio change.
Inputs: no named parameters.
rename_instanceC
Rename an instance.
Inputs: path (required), newName (required).
reparent_instanceC
Move an instance to a new parent.
Inputs: path (required), newParent (required).
respawn_playerB
Force-respawn a playtest character (tests spawn logic, retry buttons).
Inputs: player.
run_gameA
Start Run mode (F8, server-only simulation without player).
Inputs: no named parameters.
save_placeC
Save the current place (to its file). Optionally pass filePath hint for logging.
Inputs: filePath.
set_cameraB
Move Studio camera (position+focus as {x,y,z} or CFrame table, fov number).
Inputs: fov, focus, position.
set_lightingC
Set Lighting properties (ClockTime, Brightness, Ambient, OutdoorAmbient, FogEnd, ...).
Inputs: properties (required).
set_propertiesC
Set multiple properties on an instance at once.
Inputs: path (required), properties (required).
set_propertyC
Set a single property on an instance (e.g. Workspace.Part Anchored=true, Color, Position).
Inputs: path (required), property (required), value.
set_selectionC
Set Studio selection to given instance paths.
Inputs: paths (required).
stop_playtestB
Stop any running playtest / Run mode.
Inputs: no named parameters.
studio_closeA
Close all running Roblox Studio instances (taskkill).
Inputs: no named parameters.
studio_launchB
Launch Roblox Studio (optionally opening a local .rbxl/.rbxlx file or a published place). No plugin required.
Inputs: placeId, placeFile, universeId.
studio_list_placesB
List local .rbxl/.rbxlx place files in common folders (or given dirs).
Inputs: dirs.
studio_open_placeB
Open a place in Roblox Studio: either a local .rbxl/.rbxlx file or a published placeId+universeId.
Inputs: placeId, placeFile, universeId.
studio_statusA
Check if Roblox Studio is running, its PIDs, exe path and version.
Inputs: no named parameters.
teleport_playerA
Teleport a playtest character to a position (testing checkpoints, boss rooms, mazes without walking).
Inputs: player, position.
toolbox_infoB
Get details for catalog asset IDs (name, type, creator, description). No plugin required.
Inputs: assetIds (required).
toolbox_searchA
Search the Roblox Toolbox/catalog for models, meshes, images, etc. Returns asset IDs you can pass to insert_asset. No plugin required.
Inputs: keyword (required), limit, creator, category.
undoB
Undo last Studio change (ChangeHistoryService).
Inputs: no named parameters.
write_scriptC
Overwrite Source of an existing script.
Inputs: path (required), source (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 50 tools
Many tools target distinct operations, but overlaps exist: execute_luau can replicate nearly all mutation tools; playtest overlaps with play_solo/run_game/stop_playtest/get_play_state; create_instance vs bulk_create vs create_gui blur creation boundaries. Descriptions help, but an agent could easily misselect.
Nearly all tools use snake_case and follow a verb_noun pattern (create_instance, set_property, get_play_state). Minor deviations exist: noun-first names (bridge_status, toolbox_search), bare verbs (undo, redo, playtest), and mixed prefixes (studio_, toolbox_).
50 tools is excessive for the domain; many granular tools could be consolidated (e.g., create_instance/bulk_create/create_gui, multiple playtest controls). While the domain is broad, this count burdens selection and suggests over-provisioning.
Covers the major lifecycle: Studio launch/open/close, scene CRUD, scripting, GUI, asset insertion, lighting, camera, playtest, performance, player control, and undo/redo. Minor gaps like direct input simulation or place publishing exist, but execute_luau provides an escape hatch for most missing operations.
Maintenance
Related MCP Connectors
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
On-brand creative studio for AI agents: images, video, audio, and 3D.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI coding tools to control Roblox Studio for workspace exploration, instance manipulation, and script management. It provides tools for playtesting, scene rendering, and integration with the Roblox Creator Store.610MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to directly manage Roblox Studio projects by creating, reading, updating, and deleting scripts, listing instances, executing Luau code, and inspecting properties. It works through natural language, making Studio operations accessible to AI.-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to explore, edit, and automate Roblox Studio sessions locally, including browsing instance hierarchies, reading and modifying scripts, manipulating properties, creating instances, building terrain, and running playtests.1,057 npmMIT
- AlicenseAqualityCmaintenanceEnables an AI agent to drive Roblox Studio, including running Luau code, syncing Rojo projects, starting solo or multiplayer play tests, and retrieving logs, screenshots, and GUI information.11MIT