🎮 Roblox Studio Ultimate MCP Server

English | 日本語

The most comprehensive MCP (Model Context Protocol) server for Roblox Studio. 41 tools for complete Studio control from Claude Code or any MCP-compatible AI assistant.

✨ Why This Exists

The default Roblox Studio MCP only provides run_code — forcing you to manipulate script sources via string operations (gsub). This leads to:

• ❌ Pattern matching failures
• ❌ Broken end) statements
• ❌ Silent rollbacks when scripts revert
• ❌ No syntax checking before writes
• ❌ Hours wasted on simple edits

This MCP solves all of that.

🚀 Features

Script Operations (The Game Changer)

| Tool | Description | |------|-------------| | getScript | Get full source code | | setScript | Replace entire source (with syntax check + auto backup) | | editScript | Edit specific line range (partial edit!) | | insertCode | Insert code after a specific line | | removeLines | Remove specific lines | | replaceInScript | Find & replace text (plain text, safe) | | getLines | Get only specific line range (lightweight) | | getFunctionList | List all functions with line numbers | | getScriptSummary | Overview: functions, requires, globals | | listScripts | List all scripts in the game | | getAllScripts | Get all script sources at once | | searchInScripts | Search keyword across all scripts | | getReferences | Find all usages of a variable/function | | getModuleDependencies | List require() dependencies |

Safety Mechanisms

| Feature | Description | |---------|-------------| | 🔒 Syntax Check | Auto-validates before writing. Rejects bad code. | | 💾 Auto Backup | Saves previous version before every edit (10 generations) | | 🛑 Play Mode Guard | Blocks writes during Play mode (prevents silent rollbacks) | | 📝 UpdateSourceAsync | Uses ScriptEditorService for conflict-free writes |

Backup & Restore

| Tool | Description | |------|-------------| | restoreBackup | Restore from auto-saved backup | | listBackups | List available backups |

Validation

| Tool | Description | |------|-------------| | checkSyntax | Check syntax without writing | | verifyScript | Verify line count / source length | | validateAllScripts | Batch syntax check all scripts |

Instance Operations

| Tool | Description | |------|-------------| | getTree | Get instance hierarchy | | getChildren | List children (lightweight) | | getProperty / setProperty | Get/set properties | | createInstance | Create new instance | | deleteInstance | Delete instance | | cloneInstance | Clone instance | | renameInstance | Rename instance | | moveInstance | Move to different parent | | findInstances | Search instances by name/class |

Other

| Tool | Description | |------|-------------| | runCode | Execute Luau code (with output capture) | | batch | Execute multiple commands at once | | getAttribute / setAttribute | Attribute operations | | getErrors / clearErrors | Error log management | | undo / redo | Undo/redo operations | | getSelection | Get current selection | | getStudioInfo | Get Studio info |

📦 Installation

1. Clone & Build

git clone https://github.com/YOUR_USERNAME/roblox-studio-ultimate-mcp.git
cd roblox-studio-ultimate-mcp
npm install
npm run build

2. Install Studio Plugin

Copy the plugin file to your Roblox Plugins folder:

Mac:

cp plugin/UltimateMCP.rbxmx ~/Documents/Roblox/Plugins/

Windows:

copy plugin\UltimateMCP.rbxmx %LOCALAPPDATA%\Roblox\Plugins\

Or generate it from source:

bash generate-plugin.sh

3. Enable HTTP in Studio

Open Roblox Studio, then in the Command Bar (View → Command Bar):

game:GetService("HttpService").HttpEnabled = true

4. Register with Claude Code

Add to your ~/.claude.json under the appropriate project:

{
  "mcpServers": {
    "roblox_ultimate": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/roblox-studio-ultimate-mcp/dist/index.js"],
      "env": {}
    }
  }
}

5. Restart

• Restart Roblox Studio (to load the plugin)
• Restart Claude Code (to connect to the MCP)

🏗️ Architecture

Claude Code ←(stdio)→ MCP Server (Node.js) ←(HTTP)→ Studio Plugin (Luau)
                         Port 3002

• MCP Server (src/index.ts): Translates MCP tool calls to HTTP commands
• Studio Plugin (plugin/RobloxMCP.lua): Polls the server, executes commands inside Studio
• Communication: HTTP polling (300ms interval)

🔧 Usage with Other MCP Servers

This server is designed to work alongside the official Roblox Studio MCP:

| Use Case | Which MCP | |----------|-----------| | Script read/write | Ultimate (getScript/setScript) | | Play testing | Official (start_stop_play) | | Console output | Official (get_console_output) | | Instance manipulation | Ultimate | | Property changes | Ultimate |

📝 Real-World Impact

Before this MCP, a simple one-line fix in a 260-line script required:

1. run_code to get the source
2. gsub pattern matching (often fails)
3. run_code to write back
4. Pray it worked
5. Repeat 3-5 times

Now: editScript(path, 103, 103, "new code") → Done. First try.

🤝 Contributing

PRs welcome! Especially for:

• New tools
• Better error handling
• Performance improvements
• Documentation

📄 License

MIT