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

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