🎮 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