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

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

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

Copy-Item roblox-plugin\RobloxMCPPlugin.lua $env:LOCALAPPDATA\Roblox\Plugins\

Mac:

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.

python examples/studio-inject.py

inject-all-parts.py

Inject all 5 parts of the FPS game sequentially into Roblox Studio.

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:

const HTTP_PORT = 37423;  // HTTP polling endpoint
const WS_PORT = 37424;    // WebSocket (optional, for future use)

Roblox Plugin Configuration

Edit roblox-plugin/RobloxMCPPlugin.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:

// src/index.js
{
  name: 'roblox_my_tool',
  description: 'Does something cool',
  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'Description' },
    },
    required: ['param1'],
  },
}

-- 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 by Anthropic
• Powered by Claude 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