io.github.Justice219/roblox-studio-mcp

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.

Available Tools

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:

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

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