Roblox Studio MCP Server

A Model Context Protocol (MCP) server for Roblox Studio integration using WebSocket for real-time bidirectional communication.

🚀 Features

• WebSocket Communication: Direct real-time connection between MCP server and Roblox Studio
• 17 Roblox Studio Tools: Complete set of tools for object manipulation, script editing, and more
• Tool Control Panel: Built-in UI in Roblox Studio to enable/disable specific tools
• Auto-Reconnect: Robust connection handling with automatic reconnection
• Update Check: Automatic notification when a new version is available

📦 Architecture

┌─────────────────┐     stdio      ┌─────────────────┐
│   AI (Claude)   │◄──────────────►│   MCP Server    │
│   Cursor, etc.  │                │  (mcp-server.js)│
└─────────────────┘                └────────┬────────┘
                                            │
                                     WebSocket (port 3001)
                                            │
                                   ┌────────▼────────┐
                                   │  Roblox Plugin  │
                                   │  (in Roblox     │
                                   │   Studio)       │
                                   └─────────────────┘

🔧 Installation

Option 1: Install via npm (Recommended)

npm install -g roblox-mcp-vitja

🔌 Install Roblox Studio Plugin

After installing via npm, you can automatically install the required Roblox Studio bridge plugin by running:

roblox-mcp-vitja install-plugin

Note: This currently supports Windows. It copies the plugin to your local Roblox plugins folder.

Option 2: Install from GitHub

git clone https://github.com/Vltja/Roblox-MCP.git
cd Roblox-MCP
npm install

Configure MCP Client

Add to your MCP client configuration (Claude Desktop, Cursor, etc.):

With npm global install:

{
  "mcpServers": {
    "roblox-studio": {
      "command": "roblox-mcp-vitja",
      "env": {
        "MCP_WS_PORT": "3001"
      }
    }
  }
}

From source:

{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["/path/to/Roblox-MCP/mcp-server.js"],
      "env": {
        "MCP_WS_PORT": "3001"
      }
    }
  }
}

🎮 Roblox Studio Plugin

The Roblox Studio plugin is required for the MCP server to communicate with Roblox Studio.

📥 Get the Plugin

Download from Roblox Creator Store

Plugin Setup

1. Install the plugin in Roblox Studio (from the link above)
2. Open the MCP Settings panel from the toolbar
3. Configure the server IP (default: localhost)
4. Configure the WebSocket port (default: 3001)
5. Click Connect

🛠️ Available Tools

Tool	Description	Permission
tree	Get object hierarchy tree	SAFE
get	Read properties and attributes	SAFE
readLine	Read specific script lines	SAFE
getScriptInfo	Get script metadata	SAFE
scriptSearch	Search across all scripts	SAFE
scriptSearchOnly	Search in specific script	SAFE
getConsoleOutput	Read console output	SAFE
playtestControl	Start/Stop Play-Test	SAFE
copy	Clone objects	EDIT
editScript	Precise string replacement	EDIT
convertScript	Convert script type	EDIT
create	Create new objects	EDIT
modifyObject	Modify objects/scripts	EDIT
delete	Delete objects	EDIT
deleteLines	Delete script lines	EDIT
insertLines	Insert script lines	EDIT
executeCode	Execute arbitrary Lua code	EDIT

🖥️ Tool Control Panel (in Plugin UI)

The plugin includes a built-in Tool Control Panel for managing which tools are enabled:

• Allow All: Enable all tools
• Safe Only: Enable only read-only (SAFE) tools
• Individual Control: Enable/disable specific tools

⚙️ Environment Variables

Variable	Default	Description
MCP_WS_PORT	3001	WebSocket server port

🔌 WebSocket Protocol

Message Format

{
  "type": "command" | "result" | "ping" | "pong",
  "id": "unique-request-id",
  "tool": "toolName",
  "params": { ... },
  "result": { ... },
  "error": null | "error message"
}

🐛 Troubleshooting

Plugin won't connect

• Ensure MCP server is running (roblox-mcp-vitja or node mcp-server.js)
• Check firewall settings for port 3001
• Verify IP address is correct (use localhost for local)

Tools not executing

• Open Tool Control Panel in Roblox Studio and ensure tools are enabled
• Check Roblox Studio output window for errors

📜 License

MIT License

👤 Author

Vitja - GitHub