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

```bash
cd roblox-mcp-server
npm install
```

### 2. Configure Claude Code

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

```json
{
  "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

```bash
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:

```bash
# 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:

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

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

```lua
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.