ClaudeCode-Roblox-Studio-MCP/README.md

# ClaudeCode Roblox Studio MCP Server

> **Control Roblox Studio from Claude Code via MCP (Model Context Protocol)**
>
> Built with **GLM 5.1** model using **Claude Code**

This project allows any Claude Code agent/bot to directly control Roblox Studio - creating parts, writing scripts, building maps, spawning enemies, and running Lua code - all through natural language commands.

---

## Architecture

```
Claude Code  <--->  MCP Server (stdio)  <--->  HTTP/WS Bridge  <--->  Roblox Studio Plugin
    |                    |                                          |
    |  tool calls        |  HTTP polling (port 37423)              |  executes Lua
    |  (create_part,     |  WebSocket (port 37424)                 |  creates objects
    |   create_script,   |                                         |  runs game logic
    |   execute_code)    |                                         |
```

**How it works:**
1. Claude Code communicates with the MCP server via stdin/stdout (MCP protocol)
2. The MCP server runs an HTTP + WebSocket bridge on localhost
3. The Roblox Studio plugin polls the MCP server and executes commands
4. Results flow back: Plugin -> HTTP -> MCP Server -> Claude Code

---

## Quick Start (5 minutes)

### Step 1: Install Dependencies

```bash
cd ClaudeCode-Roblox-Studio-MCP
npm install
```

### Step 2: Install the Studio Plugin

Copy the plugin to your Roblox plugins folder:

```bash
# Windows
copy roblox-plugin\RobloxMCPPlugin.lua "%LOCALAPPDATA%\Roblox\Plugins\"

# Mac
cp roblox-plugin/RobloxMCPPlugin.lua ~/Library/Application\ Support/Roblox/Plugins/
```

### Step 3: Start the MCP Server

```bash
node src/index.js
```

You should see:
```
HTTP server listening on port 37423
WebSocket server listening on port 37424
Roblox Studio MCP server running on stdio
```

### Step 4: Configure Claude Code

Add to your `.claude.json` (project settings):

```json
{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["C:\\path\\to\\ClaudeCode-Roblox-Studio-MCP\\src\\index.js"]
    }
  }
}
```

Or use the auto-setup:
```bash
AutoConnect\START-HERE.bat
```

### Step 5: Open Roblox Studio

1. Open Roblox Studio
2. Create or open a place
3. Go to **Game Settings > Security > Allow HTTP Requests** and enable it
4. The plugin auto-connects (check Output window for `[RobloxMCP] Connected!`)

### Step 6: Use in Claude Code

Restart your Claude Code session, then ask it to build:

```
"Build me a military base with guard towers"
"Create a zombie survival game"
"Add 20 weapons to my FPS game"
```

---

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `roblox_create_script` | Create Lua scripts (Script, LocalScript, ModuleScript) |
| `roblox_create_part` | Create 3D parts (Block, Ball, Cylinder, Wedge, CornerWedge) |
| `roblox_create_model` | Create model containers for grouping objects |
| `roblox_create_folder` | Create organizational folders |
| `roblox_create_gui` | Create UI elements (ScreenGui, Frame, TextLabel, TextButton, etc.) |
| `roblox_set_property` | Set properties on existing objects (Position, Size, Color, etc.) |
| `roblox_get_hierarchy` | Inspect the object tree of any path |
| `roblox_delete_object` | Delete objects by path |
| `roblox_execute_code` | Run arbitrary Lua code in the command bar |
| `roblox_play` | Start playtesting |
| `roblox_stop` | Stop playtesting |
| `roblox_save_place` | Save the current place |
| `roblox_import_glb` | Import a GLB 3D model into the workspace |

---

## Tool Parameters

### roblox_create_part
```json
{
  "parentPath": "Workspace",
  "partName": "Wall1",
  "partType": "Block",
  "position": {"x": 10, "y": 5, "z": 20},
  "size": {"x": 10, "y": 10, "z": 1},
  "anchored": true,
  "color": "Bright red"
}
```

### roblox_create_script
```json
{
  "path": "Workspace.Model",
  "scriptName": "EnemyAI",
  "scriptType": "Script",
  "source": "-- Lua code here\nprint('Hello from Claude!')"
}
```

### roblox_execute_code
```json
{
  "code": "for i=1,10 do local p = Instance.new('Part', workspace) p.Position = Vector3.new(i*5, 1, 0) p.Anchored = true end"
}
```

---

## Python Injection (Alternative Method)

If the MCP plugin isn't connecting, you can inject Lua code directly into Studio's command bar using the Python scripts:

```bash
# Single script injection
python examples/studio-inject.py

# Multi-part sequential injection (for large games)
python examples/inject-all-parts.py
```

This uses Win32 API to:
1. Find the Roblox Studio window
2. Focus the command bar
3. Copy Lua code to clipboard
4. Paste and execute via simulated keyboard input

**Requirements**: Python 3.x on Windows, Roblox Studio open with a place loaded

---

## Included Example: CoD-Style FPS Game

A full Call of Duty-inspired FPS game built entirely from code:

**Map**: Urban military combat zone with buildings, cover positions, watchtowers, crates, barrels, and boundary walls.

**20 Weapons** (key to switch):
| Key | Weapon | Category | Key | Weapon | Category |
|-----|--------|----------|-----|--------|----------|
| 1 | M4A1 Carbine | Assault Rifle | 0 | UMP-45 | SMG |
| 2 | AK-47 | Assault Rifle | Q | AWP Sniper | Sniper |
| 3 | FN SCAR-H | Assault Rifle | E | Barrett M82 | Sniper |
| 4 | M16A4 | Assault Rifle | T | SVD Dragunov | Sniper |
| 5 | FAMAS F1 | Assault Rifle | Z | SPAS-12 | Shotgun |
| 6 | HK G36C | Assault Rifle | X | Remington 870 | Shotgun |
| 7 | MP5A4 | SMG | C | M249 SAW | LMG |
| 8 | FN P90 | SMG | V | M134 Minigun | LMG |
| 9 | HK MP7A2 | SMG | B | Desert Eagle | Pistol |
| | | | N | Glock 18C | Pistol |
| | | | G | RPG-7 | Launcher |

**Controls**: WASD=Move, LMB=Shoot, RMB=ADS, Shift=Sprint, Ctrl=Crouch, R=Reload

**Features**:
- First-person camera with ADS zoom + FOV transition
- Bullet trails, muzzle flash, impact sparks, explosion effects
- Recoil system with crosshair spread dynamics
- 10 enemy soldiers with AI (patrol, detect, chase, shoot)
- Health regen, damage vignette, hit markers, headshot indicators
- Kill feed, killstreak banners ("TRIPLE KILL!", "UNSTOPPABLE!")
- Minimap with enemy position dots
- Full HUD: health bar, ammo counter, weapon name, score, reload bar

---

## Auto-Connect Setup

For hands-free setup on a fresh machine:

```bash
AutoConnect\START-HERE.bat
```

This will:
1. Install Node.js dependencies
2. Start the MCP server
3. Copy the plugin to Roblox's plugins folder
4. Register the MCP server with Claude Code

---

## Troubleshooting

### Plugin doesn't connect
- **Enable HttpService**: Game Settings > Security > Allow HTTP Requests = ON
- **Check MCP server is running**: Visit `http://localhost:37423/health` in browser
- **Check Output window**: Look for `[RobloxMCP]` messages in Studio's Output

### MCP server won't start
- Ensure Node.js 18+ is installed
- Run `npm install` in the project directory
- Check ports 37423 and 37424 are not in use

### Commands time out
- The plugin polls every 0.5 seconds - slight delay is normal
- Make sure you're not in Play mode (commands work in Edit mode)
- Check Studio isn't frozen or busy

### Injection script fails
- Make sure Roblox Studio is open with a place loaded
- Run as Administrator if the window can't be focused
- Try manually: View > Command Bar, paste Lua code, press Enter

---

## File Structure

```
ClaudeCode-Roblox-Studio-MCP/
  src/
    index.js                    # MCP server (Node.js)
  roblox-plugin/
    RobloxMCPPlugin.lua         # Studio plugin v2 (HTTP polling, auto-enable)
    RobloxMCPServer_HTTP.lua    # Alternative HTTP-only server
    TestConnection.lua          # Connection test script
  examples/
    fps-game/
      part1_map.lua             # Map building (buildings, cover, towers)
      part2_weapons.lua         # Weapon data module
      part3_ai.lua              # Server handler + enemy AI system
      part4_hud.lua             # HUD elements + player setup
      part5_client.lua          # Client weapon controller
    studio-inject.py            # Direct command bar injection via Win32
    inject-all-parts.py         # Multi-part sequential injection
  AutoConnect/
    START-HERE.bat              # Main entry point
    Setup-MCP.bat               # MCP setup batch
    Setup-MCP.ps1               # PowerShell setup script
    AutoSetup.vbs               # Silent launcher
  package.json
  README.md
```

---

## For AI Agents / Bots

If you are an AI agent reading this README, here is how to use this tool:

1. **Check if the MCP server is configured**: Look in `.claude.json` for `roblox-studio` in `mcpServers`
2. **Start the server if needed**: Run `node src/index.js` in the background
3. **Ensure Roblox Studio is open** with a place loaded and HttpService enabled
4. **Use the MCP tools**: Call `roblox_create_part`, `roblox_create_script`, `roblox_execute_code`, etc.
5. **For complex builds**: Use `roblox_execute_code` with large Lua scripts to build entire games at once
6. **Fallback injection**: If MCP is not working, use the Python injection scripts (`examples/studio-inject.py`) to paste Lua directly into Studio's command bar via Win32 API

### Quick build example (via MCP tool)
```
Tool: roblox_create_part
Params: { "partName": "Ground", "parentPath": "Workspace", "partType": "Block",
          "size": {"x":100,"y":2,"z":100}, "position": {"x":0,"y":-1,"z":0},
          "anchored": true, "color": "Dark green" }
```

### Quick script example (via MCP tool)
```
Tool: roblox_create_script
Params: { "path": "ServerScriptService", "scriptName": "GameController",
          "scriptType": "Script", "source": "-- Game logic here" }
```

### Large build example (via execute_code + Python injection)
```python
# Read the Lua file, inject into Studio command bar
python examples/inject-all-parts.py
```

---

## License

MIT