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

Add FPS game example, auto-connect plugin, and Python injection tools

Browse Source 
- Updated RobloxMCPPlugin with HTTP polling (auto-enables HttpService)
- Added 20-weapon FPS game example (CoD-style)
- Added Python studio-inject.py for command bar injection via Win32 API
- Added auto-connect setup scripts (VBS + PowerShell)
- Updated MCP server with all FPS game tools

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Admin
2026-03-31 16:57:35 +04:00
Unverified
parent 9c44cb514f
commit a66533206f
16 changed files with 3448 additions and 595 deletions
Download Patch File Download Diff File Expand all files Collapse all files

424
README.md
View File

@@ -1,217 +1,349 @@
# Roblox MCP Server
# ClaudeCode-Roblox-Studio-MCP
Control Roblox Studio directly from Claude Code using the Model Context Protocol (MCP).
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.
## Overview
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
```
┌─────────────────┐ MCP (stdio) ┌──────────────────┐ HTTP Polling ┌─────────────────┐
│ Claude Code │ ◄─────────────────► │ Node.js MCP │ ◄──────────────────► │ Roblox Studio │
│ (AI Agent) │ │ Server │ (port 37423) │ Plugin │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
Express HTTP
(Health: 37423)
```
### How It Works
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
- Create and modify scripts in Roblox Studio
- Create 3D parts, models, and folders
- Create 3D parts, models, folders, and entire scenes
- Write and inject Lua scripts (Script, LocalScript, ModuleScript)
- 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
```
- Manipulate workspace hierarchy
- Execute arbitrary Lua code
- Playtest and save places automatically
- Python injection scripts for direct command bar automation
## Installation
### 1. Install Node.js Dependencies
### Prerequisites
- **Node.js** 18+ (for MCP server)
- **Claude Code** (by Anthropic)
- **Roblox Studio** (installed)
- Windows 11 or macOS
### Step 1: Clone and Install
```bash
cd roblox-mcp-server
cd ~
git clone https://github.rommark.dev/admin/ClaudeCode-Roblox-Studio-MCP.git
cd ClaudeCode-Roblox-Studio-MCP
npm install
```
### 2. Configure Claude Code
### Step 2: Configure Claude Code
Add this to your Claude Code settings (or create `.clauderc` in your home directory):
Add to your Claude Code config (`~/.claude/config.json` or `.clauderc`):
```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"
"args": ["~/ClaudeCode-Roblox-Studio-MCP/src/index.js"],
"cwd": "~/ClaudeCode-Roblox-Studio-MCP"
}
}
}
```
### 3. Install the Roblox Studio Plugin
### Step 3: Install Roblox Studio Plugin
#### Option A: Manual Installation
**Windows:**
```powershell
Copy-Item roblox-plugin\RobloxMCPPlugin.lua $env:LOCALAPPDATA\Roblox\Plugins\
```
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`
**Mac:**
```bash
cp roblox-plugin/RobloxMCPPlugin.lua ~/Library/Application\ Support/Roblox/Plugins/
```
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!)
### Step 4: Enable HTTP Requests (Critical!)
In Roblox Studio:
1. Go to **Game Settings → Security**
2. **Enable** "Allow HTTP Requests"
3. Set **Enable Studio Access to API Services** to ON
1. **File** → **Game Settings**
2. **Security** tab
3. Enable **"Enable Studio Access to API Services"**
4. Enable **"Allow HTTP Requests"**
## Usage
### Step 5: Start Using
### Starting the MCP Server
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!
```bash
npm start
## 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
```
The server will start on:
- HTTP: `http://localhost:37423` (for health checks)
- WebSocket: `ws://localhost:37424` (for Roblox Studio communication)
### Building a GUI
### 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')"
```
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
```
## Available Tools
### Scripting
| 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 |
```
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
Edit `src/index.js` to change ports:
### MCP Server Ports
Edit `src/index.js`:
```javascript
const HTTP_PORT = 37423; // Health check endpoint
const WS_PORT = 37424; // WebSocket for Roblox Studio
const HTTP_PORT = 37423; // HTTP polling endpoint
const WS_PORT = 37424; // WebSocket (optional, for future use)
```
Edit `roblox-plugin/RobloxMCPServer.lua` to change plugin settings:
### Roblox Plugin Configuration
Edit `roblox-plugin/RobloxMCPPlugin.lua`:
```lua
local CONFIG = {
PORT = 37425,
POLL_INTERVAL = 0.1,
DEBUG = true,
HOST = "localhost",
PORT = 37423,
POLL_INTERVAL = 0.5, -- seconds between polls
}
```
## Troubleshooting
### "No Roblox Studio instance connected"
### "MCP server not reachable"
- 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
**Solution:**
- Make sure the MCP server is running: `npm start`
- Check port 37423 is not in use
- Verify Claude Code config is correct
### WebSocket Connection Failed
### "HTTP Requests Blocked"
- 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
**Solution:**
- Game Settings → Security
- Enable both HTTP-related options
- Restart Roblox Studio after changing
### Scripts Not Executing
### Plugin Not Connecting
- 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
**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
### HTTP Requests Blocked
### Commands Not Executing
- Go to Game Settings → Security
- Enable "Allow HTTP Requests"
- Enable "Enable Studio Access to API Services"
**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
### 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`
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)
## Security Notes
Example:
```javascript
// src/index.js
{
name: 'roblox_my_tool',
description: 'Does something cool',
inputSchema: {
type: 'object',
properties: {
param1: { type: 'string', description: 'Description' },
},
required: ['param1'],
},
}
```
- 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
```lua
-- roblox-plugin/RobloxMCPPlugin.lua
elseif command == "myTool" then
-- Your implementation
return { success = true, result = "something" }
```
## Contributing
Contributions welcome! Feel free to open issues or pull requests.
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**