Roblox Studio MCP
Integrates with the Roblox Creator Store (Toolbox) to search for and insert models, decals, and audio assets into the development environment.
Provides comprehensive control over Roblox Studio, enabling workspace exploration, instance creation and manipulation, script management, viewport rendering, and playtest session control.
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 Studio MCP Create a red neon part at the origin and name it 'PowerCore'"
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 Studio MCP
Experimental. This is an active work-in-progress. APIs will change, features may break, and the rendered screenshots are blocky approximations — not pixel-accurate previews. Use at your own risk. Contributions and bug reports welcome.
An MCP (Model Context Protocol) server for controlling Roblox Studio from AI coding tools like OpenCode. Provides workspace exploration, instance manipulation, script management, toolbox integration, playtest controls, and viewport rendering.
Architecture
OpenCode / Claude ──stdio/MCP──> MCP Server (Node.js) ──HTTP──> Studio Plugin (Lua)
:28821 bridge polls for commandsThe MCP server runs a small HTTP server on 127.0.0.1:28821. The Roblox Studio plugin polls this server every 250ms for pending commands, executes them inside Studio, and posts results back.
Related MCP server: Roblox Studio MCP Server
Setup
1. Install dependencies and build
npm install
npm run build2. Install the Studio plugin
Automatic:
npm run install-pluginManual:
Copy plugin/RobloxStudioMCP.server.lua to your Roblox Studio plugins folder:
Platform | Path |
macOS |
|
Windows |
|
3. Activate the plugin
In Studio, click the MCP Bridge button in the toolbar. A status widget will appear showing connection state.
Note: Plugin HTTP requests are not gated by the "Allow HTTP Requests" game setting. That setting only applies to game scripts — plugins can make HTTP calls freely.
4. Configure OpenCode
The included opencode.json works when you run OpenCode from the project root:
{
"mcp": {
"roblox-studio": {
"type": "local",
"command": ["node", "dist/index.js"],
"environment": {
"ROBLOX_MCP_PORT": "28821"
}
}
},
"default_agent": "studio"
}If you want to use this from a different project, use the absolute path to dist/index.js in the command array.
Tools (6 consolidated)
All tools use an action parameter to select the specific operation.
roblox_get — Read-only queries
Action | Description |
| Check plugin connection status and get place info |
| ASCII tree view of the instance hierarchy |
| Search by name substring and/or class name |
| Get detailed info about a specific instance |
| Read all common properties of an instance |
| Class breakdown with counts for descendants |
| Get currently selected instances |
| Read recent Output window entries |
| Get texture/decal asset IDs for an instance and descendants |
roblox_manage — Instance mutations
Action | Description |
| Create Part, Model, Folder, etc. with properties |
| Batch create multiple instances at once |
| Update properties (Position, Size, Color, etc.) |
| Reset a Model's WorldPivot to bounding box center |
| Destroy an instance (undoable) |
| Clone with optional rename/reparent |
| Move an instance to a new parent |
| Select specific instances |
| Undo last action |
| Redo last undone action |
roblox_script — Script CRUD & execution
Action | Description |
| Create Script/LocalScript/ModuleScript |
| Read script source and metadata |
| Update source code (works with open editors) |
| Execute a Lua snippet in Studio context |
roblox_scene — Camera & screenshots
Action | Description |
| Render a PNG of the current viewport (geometry + color + materials, no textures) |
| Position camera explicitly or auto-frame on an instance |
roblox_toolbox — Creator Store
Action | Description |
| Search for free models/decals/audio |
| Insert a toolbox asset by ID |
| Remove all scripts from an inserted model |
roblox_playtest — Test sessions
Action | Description |
| Begin a playtest session |
| Stop the current playtest |
| Get current state (Edit/Run/Play) |
| Move camera during playtest |
| Fire a ClickDetector |
| Trigger a ProximityPrompt |
| Read game state (players, leaderstats) |
| Run Lua in the live game context |
Instance Paths
Instances are referenced by dot-separated paths from game:
Workspace -- game.Workspace
Workspace.SpawnLocation -- a SpawnLocation in Workspace
ServerScriptService.GameScript -- a script in ServerScriptService
ReplicatedStorage.Modules.Utils -- nested pathAgent
An OpenCode agent definition is included at .opencode/agents/studio.md. It configures the AI with Roblox Studio domain knowledge and tool usage patterns. The opencode.json sets it as the default agent.
Environment Variables
Variable | Default | Description |
|
| HTTP bridge port |
Known Limitations
Screenshots are software-rendered from geometry data — no textures, lighting, or post-processing. They show shapes, colors, and spatial relationships, not what Studio's viewport actually looks like.
Playtest control uses
RunService:Run()/:Stop()which works for server-side testing but doesn't fully replicate Play Solo (no local player character).Toolbox search hits the public Roblox API and may be rate-limited.
Script execution runs via
require()on a temporary ModuleScript. Some APIs may not be available in this context.Instance paths use dot-separated names, so instances with
.in their name will not resolve correctly.
License
MIT
Available Tools
6 toolsroblox_getA
Read-only queries against the Roblox Studio scene. Use the "action" parameter to select what to retrieve.
Actions:
"ping": Check plugin connection status and get place info.
"tree": Get ASCII hierarchy tree. Params: root (path, default game), maxDepth (number).
"search": Find instances by name/class. Params: query (substring), className, root, maxResults.
"instance": Get detailed info about one instance. Params: path (required), depth (children levels, default 1).
"properties": Get all readable properties. Params: path (required), properties (array of extra names).
"descendants_summary": Class-count breakdown under a root. Params: root (default Workspace).
"selection": Get the currently selected instances. Params: depth.
"output_log": Read recent Output log entries. Params: maxEntries (default 50).
"texture_info": Get texture and decal asset IDs for an instance and its descendants. Returns MeshPart TextureIDs, Decal/Texture asset IDs, and materials. Useful for understanding visual appearance without rendering textures in screenshots. Params: path (required), maxDepth (default 2).
Inputs: action (required), path, root, query, +6 more.
roblox_manageA
Mutate instances in the Roblox Studio scene.
Actions:
"create": Create a new instance. Params: className (required), name, parent (path), properties (object).
"create_multiple": Batch-create instances. Params: parent (default path), instances (array of {className, name, parent?, properties?}).
"update": Update properties on an existing instance. Params: path (required), name, properties (object).
"reset_pivot": Reset a Model's WorldPivot to its bounding box center, or a BasePart's PivotOffset to zero. Params: path (required). Use this when positioning/PivotTo is behaving unexpectedly — a stale WorldPivot far from the geometry is a common cause. Automatically done on toolbox insert, but useful for debugging.
"delete": Destroy an instance. Params: path (required).
"clone": Clone an instance tree. Params: path (required), name, parent.
"reparent": Move an instance to a new parent. Params: path (required), newParent (required).
"set_selection": Set the Studio selection. Params: paths (array of paths).
"undo": Undo last action.
"redo": Redo last undone action.
Property format: vectors as {X,Y,Z}, colors as {R,G,B} (0-1 range), booleans, strings, numbers. Example: {"Position": {"X":0,"Y":5,"Z":0}, "Size": {"X":4,"Y":1,"Z":4}, "Anchored": true, "Material": "Neon", "Color": {"R":1,"G":0,"B":0}}
Inputs: action (required), className, path, name, +5 more.
roblox_playtestA
Control Roblox Studio playtest sessions and interact with the running game.
Actions:
"start": Begin playtest (RunService:Run). Scripts execute, physics activate. Params: mode ("run"|"play", default "run").
"stop": End playtest, return to Edit mode.
"status": Get current mode (Edit/Running/Client/Server).
"move_camera": Reposition camera during playtest. Params: position {X,Y,Z}, lookAt {X,Y,Z}.
"fire_click": Trigger a ClickDetector. Params: path (instance path).
"fire_proximity": Trigger a ProximityPrompt. Params: path (instance path).
"get_state": Read game state (player count, leaderstats, runtime info).
"execute": Run Lua code in the live game context. Params: code (string).
Workflow: start → interact/observe → screenshot (via roblox_scene) → evaluate → stop → fix → repeat.
Inputs: action (required), mode, position, lookAt, +2 more.
roblox_sceneA
Control the camera and capture rendered viewport screenshots.
Actions:
"screenshot": Render a PNG image of what the camera currently sees. Returns an image you can analyze visually. Use it to verify placement, scale, orientation, and scene composition. No textures are rendered — use roblox_get action "texture_info" if you need texture/decal context. Params: maxParts (default 2000).
"move_camera": Reposition the Studio camera. Two modes: (A) Auto-frame an object: set focusInstance to an instance path (e.g. "Workspace.GasStation"). The camera automatically positions itself at a good distance and angle to see the entire object. Optional: angle (elevation in degrees, default 35), yaw (horizontal rotation in degrees, default 45). (B) Explicit placement: set position {X,Y,Z} (where the camera IS in world space) and lookAt {X,Y,Z} (the world point the camera POINTS AT). Both must be provided and must be different points. Example: position {X:50, Y:20, Z:50} lookAt {X:0, Y:0, Z:0} places camera at (50,20,50) aiming at the origin.
Typical workflow: move_camera (frame your subject) → screenshot (see the result) → evaluate → adjust.
Inputs: action (required), maxParts, focusInstance, angle, +3 more.
roblox_scriptA
Create, read, update, and execute Lua scripts in Roblox Studio.
Actions:
"create": Create a new script. Params: source (required), scriptType ("Script"|"LocalScript"|"ModuleScript"), name, parent, disabled.
"read": Read a script's source. Params: path (required).
"update": Update a script's source code. Params: path (required), source (required).
"execute": Run a Lua snippet in Studio (server context). Returns the result or error. Params: source (required). Code runs in a function body — use 'return' to get values back.
Common parent locations: "ServerScriptService" (server scripts), "StarterPlayerScripts" (local scripts), "ReplicatedStorage" (modules).
Inputs: action (required), path, source, scriptType, +3 more.
roblox_toolboxA
Search the Roblox Creator Store, insert models, and sanitize them.
Actions:
"search": Search for free models/decals/audio. Returns AssetId, Name, Creator, HasScripts, IsEndorsed. Params: query (required), category ("FreeModels"|"FreeDecals"|"FreeAudio"), maxResults (default 20). Prefer assets where HasScripts=false or IsEndorsed=true.
"insert": Insert an asset by ID. Params: assetId (required), parent (path), position {X,Y,Z}. CRITICAL: Toolbox models often contain far more than their name implies — a "gas station" may bundle pumps, signs, shelving, vehicles, lighting as descendants. Always inspect the returned hierarchy before building additional objects. Check orientation (model axes may not match your scene) and scale (toolbox models vary wildly in size, Roblox studs ≈ 0.28m).
"strip_scripts": Remove all scripts from an instance tree. Params: path (required), scriptTypes (array, default all). Always do this after inserting models with HasScripts=true.
Inputs: action (required), query, category, maxResults, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: roblox_get for read-only queries, roblox_manage for mutations, roblox_playtest for session control, roblox_scene for camera/screenshot, roblox_script for script handling, and roblox_toolbox for asset management. The actions within each tool are well-defined and non-overlapping, making tool selection straightforward for an agent.
All tool names follow a consistent 'roblox_' prefix with a descriptive suffix (e.g., get, manage, playtest, scene, script, toolbox). This pattern is uniform across all six tools, making them easily identifiable and predictable within the server's domain.
With 6 tools, the server is well-scoped for Roblox Studio automation, covering scene inspection, manipulation, playtesting, visualization, scripting, and asset management. Each tool serves a distinct and necessary function, with no redundancy or missing core areas, making the count ideal for the domain.
The tool set provides comprehensive coverage for Roblox Studio workflows, including CRUD operations (e.g., create, update, delete), scene analysis, playtesting, camera control, script management, and asset handling. There are no obvious gaps; agents can perform end-to-end tasks from asset insertion to scene evaluation and debugging.
Related MCP Connectors
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
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.
Build, validate, test-run and publish AIOS workflows from Claude Code, Codex, Cursor or VS Code.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to explore Roblox Studio game structure, read and edit scripts, and perform bulk changes locally and safely.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI tools to read the Roblox Studio game tree, edit scripts, insert models, and run playtests via the Studio MCP interface.37 npmMIT
- 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