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 commands
The 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.
Setup
1. Install dependencies and build
npm install
npm run build
2. Install the Studio plugin
Automatic:
npm run install-plugin
Manual:
Copy plugin/RobloxStudioMCP.server.lua to your Roblox Studio plugins folder:
| Platform | Path |
|---|---|
| macOS | ~/Documents/Roblox/Plugins/ |
| Windows | %LOCALAPPDATA%\Roblox\Plugins\ |
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 |
|---|---|
ping |
Check plugin connection status and get place info |
tree |
ASCII tree view of the instance hierarchy |
search |
Search by name substring and/or class name |
instance |
Get detailed info about a specific instance |
properties |
Read all common properties of an instance |
descendants_summary |
Class breakdown with counts for descendants |
selection |
Get currently selected instances |
output_log |
Read recent Output window entries |
texture_info |
Get texture/decal asset IDs for an instance and descendants |
`roblox_manage` — Instance mutations
| Action | Description |
|---|---|
create |
Create Part, Model, Folder, etc. with properties |
create_multiple |
Batch create multiple instances at once |
update |
Update properties (Position, Size, Color, etc.) |
reset_pivot |
Reset a Model's WorldPivot to bounding box center |
delete |
Destroy an instance (undoable) |
clone |
Clone with optional rename/reparent |
reparent |
Move an instance to a new parent |
set_selection |
Select specific instances |
undo |
Undo last action |
redo |
Redo last undone action |
`roblox_script` — Script CRUD & execution
| Action | Description |
|---|---|
create |
Create Script/LocalScript/ModuleScript |
read |
Read script source and metadata |
update |
Update source code (works with open editors) |
execute |
Execute a Lua snippet in Studio context |
`roblox_scene` — Camera & screenshots
| Action | Description |
|---|---|
screenshot |
Render a PNG of the current viewport (geometry + color + materials, no textures) |
move_camera |
Position camera explicitly or auto-frame on an instance |
`roblox_toolbox` — Creator Store
| Action | Description |
|---|---|
search |
Search for free models/decals/audio |
insert |
Insert a toolbox asset by ID |
strip_scripts |
Remove all scripts from an inserted model |
`roblox_playtest` — Test sessions
| Action | Description |
|---|---|
start |
Begin a playtest session |
stop |
Stop the current playtest |
status |
Get current state (Edit/Run/Play) |
move_camera |
Move camera during playtest |
fire_click |
Fire a ClickDetector |
fire_proximity |
Trigger a ProximityPrompt |
get_state |
Read game state (players, leaderstats) |
execute |
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
ReplicatedS
Tools 6
roblox_getRead-only queries for workspace hierarchy, instances, properties, and logs.roblox_manageInstance mutations including creation, updates, deletion, and selection.roblox_scriptScript CRUD operations and Lua snippet execution.roblox_sceneCamera control and viewport screenshot rendering.roblox_toolboxIntegration with the Roblox Creator Store for searching and inserting assets.roblox_playtestControl and monitor active playtest sessions.Environment Variables
ROBLOX_MCP_PORTThe port used for the HTTP bridge between the MCP server and the Roblox Studio plugin.