Skip to main content
Glama

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.

Related MCP server: Roblox Studio MCP Server

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

Available Tools

6 tools
roblox_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

    A4.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT