ClaudeCode-Roblox-Studio-MCP/README.md

ClaudeCode Roblox Studio MCP Server

Control Roblox Studio from Claude Code via MCP (Model Context Protocol)

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

cd ClaudeCode-Roblox-Studio-MCP
npm install

Step 2: Install the Studio Plugin

Copy the plugin to your Roblox plugins folder:

# 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

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

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

Or use the auto-setup:

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

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

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

roblox_execute_code

{
  "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:

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

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)

# Read the Lua file, inject into Studio command bar
python examples/inject-all-parts.py

---

License

MIT