🎮 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:

run_code to get the source
gsub pattern matching (often fails)
run_code to write back
Pray it worked
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

Roblox Studio Ultimate MCP Server