ClaudeCode-Roblox-Studio-MCP/README.md

Roblox MCP Server

Control Roblox Studio directly from Claude Code using the Model Context Protocol (MCP).

Features

• Create and modify scripts in Roblox Studio
• Create 3D parts, models, and folders
• Build GUI elements (ScreenGui, Frame, TextButton, etc.)
• Set properties on any object
• Get hierarchy information
• Execute Lua code
• Play/Stop playtesting
• Save places

Architecture

Claude Code <--(MCP)--> Node.js MCP Server <--(WebSocket)--> Roblox Studio Plugin

Installation

1. Install Node.js Dependencies

cd roblox-mcp-server
npm install

2. Configure Claude Code

Add this to your Claude Code settings (or create .clauderc in your home directory):

{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["/mnt/c/Users/Admin/roblox-mcp-server/src/index.js"],
      "cwd": "/mnt/c/Users/Admin/roblox-mcp-server"
    }
  }
}

3. Install the Roblox Studio Plugin

Option A: Manual Installation

1. Copy roblox-plugin/RobloxMCPServer.lua to:

   • Windows: C:\Users\YOUR_USERNAME\AppData\Local\Roblox\Plugins\RobloxMCPServer.lua
   • Mac: ~/Library/Application Support/Roblox/Plugins/RobloxMCPServer.lua

2. Open Roblox Studio

3. Go to Plugins → Plugin Management

4. Find "RobloxMCPServer" and enable it

Option B: In-Place Installation

1. Open Roblox Studio

2. Create a new place or open an existing one

3. In ServerScriptService, create a new Script

4. Paste the contents of roblox-plugin/RobloxMCPServer.lua

5. The server will auto-start when you press Play

4. Enable HTTP Requests (Important!)

In Roblox Studio:

1. Go to Game Settings → Security
2. Enable "Allow HTTP Requests"
3. Set Enable Studio Access to API Services to ON

Usage

Starting the MCP Server

npm start

The server will start on:

• HTTP: http://localhost:37423 (for health checks)
• WebSocket: ws://localhost:37424 (for Roblox Studio communication)

Starting Roblox Studio Communication

1. Open Roblox Studio with the plugin installed
2. Press Play to start the server script
3. You should see a status indicator in the top-right corner
4. The MCP server will automatically connect

Using with Claude Code

Once connected, you can ask Claude to:

# Create a script
"Create a Script in Workspace that prints 'Hello World'"

# Create a part
"Create a red block part at position 0, 10, 0 in Workspace"

# Build a GUI
"Create a ScreenGui with a TextButton that says 'Click Me'"

# Get hierarchy
"Show me the hierarchy of Workspace"

# Execute code
"Execute: print('Testing command')"

Available Tools

Tool	Description
roblox_create_script	Create a Script, LocalScript, or ModuleScript
roblox_create_part	Create 3D parts (Block, Ball, Cylinder, etc.)
roblox_create_model	Create model containers
roblox_create_folder	Create folders for organization
roblox_create_gui	Create GUI elements
roblox_set_property	Set properties on existing objects
roblox_get_hierarchy	Get the object hierarchy
roblox_delete_object	Delete an object by path
roblox_execute_code	Execute arbitrary Lua code
roblox_play	Start playtest
roblox_stop	Stop playtest
roblox_save_place	Save the current place

Configuration

Edit src/index.js to change ports:

const HTTP_PORT = 37423;  // Health check endpoint
const WS_PORT = 37424;    // WebSocket for Roblox Studio

Edit roblox-plugin/RobloxMCPServer.lua to change plugin settings:

local CONFIG = {
    PORT = 37425,
    POLL_INTERVAL = 0.1,
    DEBUG = true,
}

Troubleshooting

"No Roblox Studio instance connected"

• Make sure Roblox Studio is open
• Make sure the server script is running (press Play)
• Check that HTTP requests are enabled in Game Settings
• Look for the status indicator in the top-right corner

WebSocket Connection Failed

• Check that the MCP server is running (npm start)
• Verify the WS_PORT matches between server and plugin
• Check Windows Firewall if connection is refused

Scripts Not Executing

• Make sure the script type is correct (Script vs LocalScript vs ModuleScript)
• Check the Output window in Roblox Studio for errors
• Verify the parent path is correct

HTTP Requests Blocked

• Go to Game Settings → Security
• Enable "Allow HTTP Requests"
• Enable "Enable Studio Access to API Services"

Development

Project Structure

roblox-mcp-server/
├── src/
│   └── index.js          # MCP server + WebSocket server
├── roblox-plugin/
│   ├── RobloxMCPPlugin.lua       # Toolbar plugin (optional)
│   └── RobloxMCPServer.lua       # Server script (required)
├── package.json
└── README.md

Adding New Tools

1. Add the tool definition to src/index.js in the ListToolsRequestSchema handler
2. Add a case in the CallToolRequestSchema handler
3. Add a corresponding handler in roblox-plugin/RobloxMCPServer.lua

Security Notes

• This plugin allows executing arbitrary Lua code in Roblox Studio
• Only use in trusted environments
• HTTP requests must be enabled in Roblox Studio
• Consider using a reverse proxy for production deployments

License

MIT

Contributing

Contributions welcome! Feel free to open issues or pull requests.