Skip to main content
Glama
Roblox Studio MCP Bridge

Roblox Studio MCP Bridge

by Justice219

Roblox Studio MCP Bridge

A Model Context Protocol (MCP) server that connects AI coding assistants like Claude Code directly to Roblox Studio. Read, create, modify, and delete instances in the DataModel — all from your terminal.

How It Works

Claude Code (MCP Client)
        |
   MCP Server (stdio)
        |
   HTTP Bridge (localhost:3001)
        |
   Studio Plugin (polls every 200ms)
        |
   Roblox Studio DataModel

The bridge has two halves:

  1. MCP Server (TypeScript) — Runs locally, exposes 14 tools via MCP over stdio, and serves an HTTP API on localhost:3001

  2. Studio Plugin (Luau) — Polls the HTTP API for commands, executes them against the DataModel, and returns results

All write operations are wrapped in ChangeHistoryService, so every change can be undone with Ctrl+Z in Studio.

Related MCP server: MCP-Claude

Available Tools

Tool

Type

Description

get_descendants

Read

Get all descendants with paths, optional maxDepth

get_children

Read

Get immediate children of an instance

get_properties

Read

Get serialized properties of an instance

find_instances

Read

Search by className and/or namePattern

get_services

Read

List all DataModel services

get_selection

Read

Get currently selected instances in Studio

create_instance

Write

Create a new Instance with properties

set_properties

Write

Modify properties on an existing instance

delete_instance

Write

Destroy an instance (undo-supported)

clone_instance

Write

Clone an instance to a new parent

move_instance

Write

Reparent an instance

set_selection

Write

Set the Studio selection

insert_service

Write

Insert a service via game:GetService()

execute_luau

Write

Execute arbitrary Luau code in the plugin context

Paths use dot-notation starting from game, e.g. game.Workspace.SpawnLocation.

Prerequisites

  • Node.js 18+

  • Roblox Studio

  • Rojo 7+ (aftman or standalone install)

Installation

1. Clone the repository

git clone https://github.com/Justice219/roblox-studio-mcp.git
cd roblox-studio-mcp

2. Install dependencies and build

npm install
npm run build

Or install directly from npm:

npm install -g @jamesworkbenchcrm/roblox-studio-mcp

3. Build and install the Studio plugin

Using Rojo:

rojo build plugin.project.json -o MCPBridge.rbxmx

Then copy the plugin file to your Roblox plugins folder:

OS

Path

macOS

~/Documents/Roblox/Plugins/MCPBridge.rbxmx

Windows

%LOCALAPPDATA%\Roblox\Plugins\MCPBridge.rbxmx

Or build directly to the plugins folder:

# macOS
rojo build plugin.project.json -o ~/Documents/Roblox/Plugins/MCPBridge.rbxmx

# Windows
rojo build plugin.project.json -o "%LOCALAPPDATA%\Roblox\Plugins\MCPBridge.rbxmx"

4. Enable HttpService in Studio

Open Roblox Studio, then:

Home → Game Settings → Security → Allow HTTP Requests → ON

This is required for the plugin to communicate with the local MCP server.

5. Configure your MCP client

Add the server to your MCP client configuration.

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["/absolute/path/to/roblox-studio-mcp/dist/index.js"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["/absolute/path/to/roblox-studio-mcp/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/ with the actual path where you cloned the repo.

6. Restart Studio and your MCP client

  • Restart Roblox Studio (or reload plugins) — you should see an "MCP Bridge" button in the toolbar

  • Restart Claude Code / your MCP client

  • The plugin status widget will show a green dot when connected

Usage

Once connected, your AI assistant can manipulate Studio directly:

"Create a Part named SpawnPad in Workspace at position 0, 5, 0"
"Get all children of ServerScriptService"
"Find all instances with className RemoteEvent"
"Set the BrickColor of game.Workspace.SpawnPad to Bright green"

The assistant uses the MCP tools to read the DataModel, create instances, set properties, and more — all reflected live in Studio with full undo support.

Configuration

Environment Variable

Default

Description

MCP_BRIDGE_PORT

3001

HTTP bridge port

MCP_BRIDGE_PORT=4000 npm start

Development

# Watch mode — recompiles on file changes
npm run dev

# Type-check without emitting
npm run typecheck

# Build
npm run build

# Start the server
npm start

Architecture

src/
├── index.ts           # Entry point — wires up all components
├── types.ts           # Interfaces, constants, command type definitions
├── mcp-server.ts      # MCP tool definitions (14 tools with Zod validation)
├── http-bridge.ts     # Express HTTP server (poll/result/heartbeat endpoints)
└── command-queue.ts   # In-memory command queue with timeout management

plugin/
├── init.server.luau   # Plugin entry point — polling loop, UI, toolbar
└── modules/
    ├── CommandRouter.luau  # Dispatches commands to handlers
    ├── HttpClient.luau     # HTTP requests to the bridge
    ├── PathResolver.luau   # Dot-notation path ↔ Instance resolution
    └── Serializer.luau     # Roblox type ↔ JSON serialization

Security

  • The HTTP bridge only binds to 127.0.0.1 — it is never exposed to the network

  • Write operations are wrapped in ChangeHistoryService for undo support

  • Commands timeout after 30 seconds

  • Connection requires heartbeat every 10 seconds

  • execute_luau runs code in the plugin context with no sandboxing — only use with trusted input

Supported Roblox Types

The serializer handles bidirectional conversion for:

Vector3 · Vector2 · CFrame · Color3 · BrickColor · UDim · UDim2 · Rect · NumberSequence · ColorSequence · NumberRange · Enum · Instance · Font · PhysicalProperties · Ray

All types use a { _type: "TypeName", ... } JSON format for lossless round-tripping.

Troubleshooting

Plugin shows red dot / "Disconnected"

  • Make sure the MCP server is running (npm start)

  • Check that HttpService is enabled in Studio

  • Verify the port matches (default 3001)

"Plugin not connected" error in Claude Code

  • Open Studio and check the MCP Bridge toolbar button is enabled

  • The plugin auto-starts on load — try reloading plugins

  • Check Studio's Output window for error messages

Port already in use

  • Another instance may be running. Kill it or use a different port:

    MCP_BRIDGE_PORT=4000 npm start

npm

npm install -g @jamesworkbenchcrm/roblox-studio-mcp

https://www.npmjs.com/package/@jamesworkbenchcrm/roblox-studio-mcp

License

MIT

Available Tools

14 tools
clone_instanceB

Clone an instance to a new parent location

Inputs: sourcePath (required), destinationParent (required).

create_instanceB

Create a new Instance with the given className under the specified parent

Inputs: parent (required), className (required), properties.

delete_instanceA

Destroy an instance (and all its descendants)

Inputs: path (required).

execute_luauA

Execute arbitrary Luau code in the Studio plugin context. Returns the result of the last expression.

Inputs: code (required).

find_instancesB

Search for instances by className and/or name pattern

Inputs: className, maxResults, searchRoot, namePattern.

get_childrenA

Get immediate children of an instance at the given path

Inputs: path (required).

get_descendantsA

Get all descendants of an instance at the given path, with their classNames and full paths

Inputs: path (required), maxDepth.

get_propertiesA

Get serialized properties of an instance (with _type tags for Vector3, CFrame, etc.)

Inputs: path (required), properties.

get_selectionA

Get the currently selected objects in Roblox Studio

Inputs: no named parameters.

get_servicesA

List all services currently in the DataModel (Workspace, ReplicatedStorage, etc.)

Inputs: no named parameters.

insert_serviceB

Insert/get a service via game:GetService() (e.g. TeleportService, Teams)

Inputs: serviceName (required).

move_instanceA

Move (reparent) an instance to a new parent

Inputs: path (required), newParent (required).

set_propertiesB

Set properties on an existing instance

Inputs: path (required), properties (required).

set_selectionB

Set the Roblox Studio selection to the given instances

Inputs: paths (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: navigation (get_children, get_descendants), property access/modification (get_properties, set_properties), instance lifecycle (create, delete, clone, move), selection (get_selection, set_selection), service handling (get_services, insert_service), and script execution (execute_luau). Even the related get_services and insert_service are distinguished by scope (list all vs. get/create one).

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case: get_, set_, create_, delete_, clone_, move_, insert_, execute_, find_. The naming is predictable and uniform across the entire set.

    Tool Count5/5

    14 tools is well within the ideal 3-15 range. Each tool covers a specific operation without redundancy, making the set concise but comprehensive for interacting with Roblox Studio.

    Completeness5/5

    The tool surface covers the full lifecycle of instance manipulation (create, read, update, delete, clone, move), hierarchy traversal, selection, service access, and arbitrary Lua execution for advanced operations. No critical gaps are apparent for the stated purpose of bridging Roblox Studio.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers