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
ReplicatedStorage.Modules.Utils -- nested path
Agent
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 |
|---|---|---|
ROBLOX_MCP_PORT | 28821 | 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