io.github.Justice219/roblox-studio-mcp

Official

by Justice219 · Luau

Connect AI assistants to Roblox Studio — manipulate the DataModel with 14 tools

Manipulate Roblox Studio DataModel with 14 tools for game development.

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

code

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

The bridge has two halves:

MCP Server (TypeScript) — Runs locally, exposes 14 tools via MCP over stdio, and serves an HTTP API on localhost:3001
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.

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

bash

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

2. Install dependencies and build

bash

npm install
npm run build

Or install directly from npm:

bash

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

3. Build and install the Studio plugin

Using Rojo:

bash

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:

bash

# 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):

json

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

Claude Desktop (claude_desktop_config.json):

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:

code

"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

bash

MCP_BRIDGE_PORT=4000 npm start

Development

bash

# 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

code

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:
bash
```
MCP_BRIDGE_PORT=4000 npm start
```

npm

bash

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

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

License

MIT

Install

Configuration

Environment variables

MCP_BRIDGE_PORT

HTTP bridge port for Studio plugin communication

claude_desktop_config.json

{
  "mcpServers": {
    "roblox-studio-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@jamesworkbenchcrm/roblox-studio-mcp@1.0.1"
      ],
      "env": {
        "MCP_BRIDGE_PORT": "<YOUR_MCP_BRIDGE_PORT>"
      }
    }
  }
}