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