ClaudeCode-Roblox-Studio-MCP/README.md

# ClaudeCode-Roblox-Studio-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 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

```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

Add to your Claude Code config (`~/.claude/config.json` or `.clauderc`):

```json
{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["~/ClaudeCode-Roblox-Studio-MCP/src/index.js"],
      "cwd": "~/ClaudeCode-Roblox-Studio-MCP"
    }
  }
}
```

### Step 3: Install Roblox Studio Plugin

**Windows:**
```powershell
Copy-Item roblox-plugin\RobloxMCPPlugin.lua $env:LOCALAPPDATA\Roblox\Plugins\
```

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

### Step 4: Enable HTTP Requests (Critical!)

In Roblox Studio:
1. **File** → **Game Settings**
2. **Security** tab
3. Enable **"Enable Studio Access to API Services"**
4. Enable **"Allow HTTP Requests"**

### Step 5: Start Using

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

```
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
```

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