io.github.Justice219/roblox-studio-mcp
Connect AI assistants to Roblox Studio — manipulate the DataModel with 14 tools
Open source Open in the app JSON README (API)
About
Connect AI assistants to Roblox Studio — manipulate the DataModel with 14 tools
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- justice219
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Stars
- 2
- Last push
- 2026-02-11T23:28:58Z
- Repository state
- ativo
- Language
- Luau
- Added
- 2026-08-29 03:02:00
- Updated
- 2026-08-29 03:02:00
- Origin id
io.github.Justice219/roblox-studio-mcp
README
# Roblox Studio MCP Bridge
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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
| 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](https://github.com/LPGhatguy/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:
```
"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
```
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