admin/ClaudeCode-Roblox-Studio-MCP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive README with installation guide, 20-weapon reference, and AI agent instructions

Browse Source 
- Full architecture diagram and data flow explanation
- Step-by-step installation (5 minutes)
- Complete MCP tool reference with parameter examples
- Python injection fallback documentation
- 20-weapon FPS game reference table
- Troubleshooting guide
- AI agent / bot integration instructions
- File structure overview

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Admin
2026-03-31 17:01:53 +04:00
Unverified
parent a66533206f
commit 2075b56f60
1 changed files with 277 additions and 308 deletions
Download Patch File Download Diff File Expand all files Collapse all files

585
README.md
View File

@@ -1,349 +1,318 @@
# ClaudeCode-Roblox-Studio-MCP
# ClaudeCode Roblox Studio MCP Server
A Model Context Protocol (MCP) server that enables **Claude Code** (by Anthropic) to directly control **Roblox Studio** - create games, manipulate objects, write scripts, and build experiences through natural language commands.
> **Control Roblox Studio from Claude Code via MCP (Model Context Protocol)**
## Overview
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.
This project creates a bidirectional bridge between Claude Code and Roblox Studio using:
- **MCP Protocol** (stdio) for Claude Code communication
- **HTTP Polling** for Roblox Studio plugin communication
- **Express.js** server for command queuing and result handling
---
## Architecture Diagram
## Architecture
```
┌─────────────────┐ MCP (stdio) ┌──────────────────┐ HTTP Polling ┌─────────────────┐
│ Claude Code │ ◄─────────────────► │ Node.js MCP │ ◄──────────────────► │ Roblox Studio │
│ (AI Agent) │ │ Server │ (port 37423) │ Plugin │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
Express HTTP
(Health: 37423)
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
**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
1. **Claude Code** connects to the MCP server via stdio
2. **MCP Server** exposes tools that Claude can call (create_part, create_script, etc.)
3. **Commands** are queued in the MCP server's memory
4. **Roblox Plugin** polls the HTTP endpoint for new commands
5. **Plugin executes** commands in Roblox Studio and sends results back
6. **Results** are returned to Claude Code via the MCP protocol
---
## Features
## Quick Start (5 minutes)
- Create 3D parts, models, folders, and entire scenes
- Write and inject Lua scripts (Script, LocalScript, ModuleScript)
- Build GUI elements (ScreenGui, Frame, TextButton, etc.)
- Manipulate workspace hierarchy
- Execute arbitrary Lua code
- Playtest and save places automatically
- Python injection scripts for direct command bar automation
## Installation
### Prerequisites
- **Node.js** 18+ (for MCP server)
- **Claude Code** (by Anthropic)
- **Roblox Studio** (installed)
- Windows 11 or macOS
### Step 1: Clone and Install
### Step 1: Install Dependencies
```bash
cd ~
git clone https://github.rommark.dev/admin/ClaudeCode-Roblox-Studio-MCP.git
cd ClaudeCode-Roblox-Studio-MCP
npm install
```
### Step 2: Configure Claude Code
### Step 2: Install the Studio Plugin
Add to your Claude Code config (`~/.claude/config.json` or `.clauderc`):
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": ["~/ClaudeCode-Roblox-Studio-MCP/src/index.js"],
"cwd": "~/ClaudeCode-Roblox-Studio-MCP"
"args": ["C:\\path\\to\\ClaudeCode-Roblox-Studio-MCP\\src\\index.js"]
}
}
}
```
### Step 3: Install Roblox Studio Plugin
**Windows:**
```powershell
Copy-Item roblox-plugin\RobloxMCPPlugin.lua $env:LOCALAPPDATA\Roblox\Plugins\
```
**Mac:**
Or use the auto-setup:
```bash
cp roblox-plugin/RobloxMCPPlugin.lua ~/Library/Application\ Support/Roblox/Plugins/
AutoConnect\START-HERE.bat
```
### Step 4: Enable HTTP Requests (Critical!)
### Step 5: Open Roblox Studio
In Roblox Studio:
1. **File** → **Game Settings**
2. **Security** tab
3. Enable **"Enable Studio Access to API Services"**
4. Enable **"Allow HTTP Requests"**
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 5: Start Using
### Step 6: Use in Claude Code
1. Start the MCP server: `npm start`
2. Open Roblox Studio
3. The plugin will auto-connect (look for "RobloxMCP" toolbar)
4. Start chatting with Claude Code to build your game!
## Available MCP Tools
| Tool | Description | Example |
|------|-------------|---------|
| `roblox_create_script` | Create Script/LocalScript/ModuleScript | "Create a Script in Workspace that prints hello" |
| `roblox_create_part` | Create 3D parts (Block, Ball, Cylinder, Wedge, CornerWedge) | "Create a red block at position 5, 10, 0" |
| `roblox_create_model` | Create model containers | "Create a model named Weapons in Workspace" |
| `roblox_create_folder` | Create folders for organization | "Create a folder named Scripts in Workspace" |
| `roblox_create_gui` | Create GUI elements | "Create a ScreenGui with a start button" |
| `roblox_set_property` | Set properties on objects | "Set the color of Workspace.Part1 to blue" |
| `roblox_get_hierarchy` | Explore object tree | "Show me the Workspace hierarchy" |
| `roblox_delete_object` | Delete objects by path | "Delete Workspace.OldPart" |
| `roblox_execute_code` | Run arbitrary Lua code | "Execute: print('Hello from Claude')" |
| `roblox_play` | Start playtest | "Start playtest in Client mode" |
| `roblox_stop` | Stop playtest | "Stop the playtest" |
| `roblox_save_place` | Save current place | "Save the place" |
## Usage Examples
### Creating a Simple Game
Ask Claude:
```
Create an obstacle course game with:
- A green starting platform at 0, 1, 0
- 5 red checkpoint platforms going upward
- A spinning part at the end
- A kill brick floor called Lava
```
### Building a GUI
Restart your Claude Code session, then ask it to build:
```
Create a ScreenGui with:
- A dark semi-transparent frame
- A title saying "MY GAME"
- A green start button
- Make the button print "Started!" when clicked
"Build me a military base with guard towers"
"Create a zombie survival game"
"Add 20 weapons to my FPS game"
```
### Scripting
```
Create a Script in Workspace.Part that makes it spin continuously
```
## Python Injection Scripts
The `examples/` folder includes Python scripts for direct injection into Roblox Studio:
### studio-inject.py
Inject a single Lua script into the Roblox Studio command bar using Win32 API.
```bash
python examples/studio-inject.py
```
### inject-all-parts.py
Inject all 5 parts of the FPS game sequentially into Roblox Studio.
```bash
python examples/inject-all-parts.py
```
**Requirements:**
- Windows 11
- Roblox Studio must be open
- Python 3.x
## Examples Folder
The `examples/` folder contains:
- `fps-game/` - Complete 5-part FPS game setup (CoD style)
- `demo_game.lua` - Simple obby game example
- `spinning_part.lua` - Rotating part script
- `start_button.lua` - Start button GUI
### FPS Game Parts
1. **Part 1**: Map + Infrastructure (buildings, cover, lighting)
2. **Part 2**: Weapon System (weapon data module, client weapon controller)
3. **Part 3**: Enemy AI + Server Handler (AI bots, game server script)
4. **Part 4**: HUD + Player Scripts (crosshair, minimap, damage effects)
5. **Part 5**: Weapon Client Script (final weapon controller)
## Project Structure
```
ClaudeCode-Roblox-Studio-MCP/
├── src/
│ └── index.js # Main MCP server + Express/HTTP
├── roblox-plugin/
│ └── RobloxMCPPlugin.lua # HTTP polling plugin for Studio
├── examples/
│ ├── fps-game/
│ │ ├── part1_map.lua # Map infrastructure
│ │ ├── part2_weapons.lua # Weapon system
│ │ ├── part3_ai.lua # Enemy AI + server
│ │ ├── part4_hud.lua # HUD + player scripts
│ │ └── part5_client.lua # Weapon client script
│ ├── studio-inject.py # Single script injection
│ └── inject-all-parts.py # Multi-part injection
├── package.json
└── README.md # This file
```
## Configuration
### MCP Server Ports
Edit `src/index.js`:
```javascript
const HTTP_PORT = 37423; // HTTP polling endpoint
const WS_PORT = 37424; // WebSocket (optional, for future use)
```
### Roblox Plugin Configuration
Edit `roblox-plugin/RobloxMCPPlugin.lua`:
```lua
local CONFIG = {
HOST = "localhost",
PORT = 37423,
POLL_INTERVAL = 0.5, -- seconds between polls
}
```
## Troubleshooting
### "MCP server not reachable"
**Solution:**
- Make sure the MCP server is running: `npm start`
- Check port 37423 is not in use
- Verify Claude Code config is correct
### "HTTP Requests Blocked"
**Solution:**
- Game Settings → Security
- Enable both HTTP-related options
- Restart Roblox Studio after changing
### Plugin Not Connecting
**Solution:**
- Check Output window in Roblox Studio
- Verify plugin is in correct Plugins folder
- Make sure HttpService is enabled
- Try clicking the toolbar button manually
### Commands Not Executing
**Solution:**
- Check for Lua errors in Output window
- Verify parent paths exist
- Make sure object names don't contain special characters
## Security Considerations
⚠️ **Important Security Notes:**
- This plugin allows executing arbitrary Lua code
- Only use in trusted development environments
- HTTP requests must be enabled (security trade-off)
- Consider using a reverse proxy for production
- Review all code before execution in production games
## Development
### Adding New Tools
1. Add tool definition in `src/index.js` (in `ListToolsRequestSchema` handler)
2. Add handler in `CallToolRequestSchema` handler
3. Implement in `roblox-plugin/RobloxMCPPlugin.lua` (add to `handleCommand` function)
Example:
```javascript
// src/index.js
{
name: 'roblox_my_tool',
description: 'Does something cool',
inputSchema: {
type: 'object',
properties: {
param1: { type: 'string', description: 'Description' },
},
required: ['param1'],
},
}
```
```lua
-- roblox-plugin/RobloxMCPPlugin.lua
elseif command == "myTool" then
-- Your implementation
return { success = true, result = "something" }
```
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request
## License
MIT License - feel free to use in your projects!
## Credits
- Built with [Model Context Protocol](https://github.com/modelcontextprotocol) by Anthropic
- Powered by [Claude Code](https://claude.ai/code)
- For Roblox Studio game development
## Support
For issues, questions, or suggestions:
- Open an issue on GitHub
- Check the Troubleshooting section
- Review the examples in `examples/`
## Changelog
### v2.0.0 (2025-03-31)
- Updated to HTTP polling architecture
- Added Python injection scripts
- Added complete FPS game example
- Improved plugin with toolbar UI
- Added comprehensive examples folder
### v1.0.0 (2025-01-29)
- Initial release
- 12 MCP tools implemented
- WebSocket communication (deprecated)
- Full CRUD operations for Roblox objects
---
**Made with ❤️ for Roblox developers using AI**
## 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