Roblox Studio MCP Server

A powerful MCP (Model Context Protocol) server that gives AI assistants comprehensive access to Roblox Studio projects. Explore game architecture, analyze scripts, debug issues, and understand complex Roblox projects through 18 specialized AI tools including mass operations for bulk editing.

⚡ Quick Start (One Command)

For Claude Code users:

1claude mcp add robloxstudio -- npx -y robloxstudio-mcp

For other MCP clients (Claude Desktop, etc.):

1{
2  "mcpServers": {
3    "robloxstudio-mcp": {
4      "command": "npx",
5      "args": ["-y", "robloxstudio-mcp"],
6      "description": "Advanced Roblox Studio integration for AI assistants"
7    }
8  }
9}

🔌 Studio Plugin Setup (Required)

The MCP server requires a companion Roblox Studio plugin:

1. Roblox Creator Store (Easiest ⭐):

   • Install from: https://create.roblox.com/store/asset/132985143757536
   • Click "Install" → Opens in Studio automatically

2. Manual download:

   • Download MCPPlugin.rbxmx
   • Save to your %LOCALAPPDATA%/Roblox/Plugins folder

3. Advanced setup:

   • See studio-plugin/INSTALLATION.md for other methods

After installation:

• ✅ Enable "Allow HTTP Requests" in Game Settings → Security
• 🔘 Click the "MCP Server" button in the Plugins toolbar
• 🟢 Status should show "Connected" when working

🏗️ Architecture Overview

This is a dual-component system bridging Roblox Studio with AI assistants:

1%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#718096', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#2b6cb0', 'tertiaryColor':'#319795'}}}%%
2graph TB
3    subgraph AI_ENV ["🤖 AI Environment"]
4        AI["🤖 AI Assistant<br/>Claude Code/Desktop"]
5        MCP["📡 MCP Server<br/>Node.js + TypeScript"]
6    end
7    
8    subgraph COMM_LAYER ["🔗 Communication Layer"]
9        HTTP["🌐 HTTP Bridge<br/>localhost:3002"]
10        QUEUE["📋 Request Queue<br/>UUID tracking"]
11    end
12    
13    subgraph STUDIO_ENV ["🎮 Roblox Studio Environment"]
14        PLUGIN["🎮 Studio Plugin<br/>Luau Script"]
15        STUDIO["🎯 Roblox Studio<br/>APIs & Data"]
16    end
17    
18    subgraph TOOLS ["🛠️ 18 AI Tools"]
19        FILE["📁 File System<br/>Trees, Search"]
20        CONTEXT["🎯 Studio Context<br/>Services, Objects"]
21        PROPS["🔍 Properties<br/>Get, Set, Mass Ops"]
22        CREATE["🏗️ Object Creation<br/>Single, Mass, Properties"]
23        PROJECT["🏢 Project Analysis<br/>Smart Structure"]
24    end
25    
26    AI -->|stdio| MCP
27    MCP -->|HTTP POST| HTTP
28    HTTP -->|Queue Request| QUEUE
29    PLUGIN -->|Poll every 500ms| HTTP
30    HTTP -->|Pending Work| PLUGIN
31    PLUGIN -->|Execute APIs| STUDIO
32    STUDIO -->|Return Data| PLUGIN
33    PLUGIN -->|HTTP Response| HTTP
34    HTTP -->|Resolve Promise| MCP
35    MCP -->|Tool Result| AI
36    
37    MCP -.->|Exposes| FILE
38    MCP -.->|Exposes| CONTEXT  
39    MCP -.->|Exposes| PROPS
40    MCP -.->|Exposes| CREATE
41    MCP -.->|Exposes| PROJECT
42    
43    classDef aiStyle fill:#1e40af,stroke:#3b82f6,stroke-width:2px,color:#ffffff
44    classDef mcpStyle fill:#7c3aed,stroke:#8b5cf6,stroke-width:2px,color:#ffffff
45    classDef httpStyle fill:#ea580c,stroke:#f97316,stroke-width:2px,color:#ffffff
46    classDef pluginStyle fill:#059669,stroke:#10b981,stroke-width:2px,color:#ffffff
47    classDef studioStyle fill:#dc2626,stroke:#ef4444,stroke-width:2px,color:#ffffff
48    classDef toolStyle fill:#0891b2,stroke:#06b6d4,stroke-width:2px,color:#ffffff
49    
50    class AI aiStyle
51    class MCP mcpStyle
52    class HTTP,QUEUE httpStyle
53    class PLUGIN pluginStyle
54    class STUDIO studioStyle
55    class FILE,CONTEXT,PROPS,CREATE,PROJECT toolStyle

Key Components:

• 🧠 MCP Server (Node.js/TypeScript) - Exposes 18 tools via stdio for AI integration
• 🔗 HTTP Bridge - Request/response queue on localhost:3002 with 30s timeouts
• 🎮 Studio Plugin (Luau) - Polls every 500ms, executes Studio API calls, handles errors
• 📊 Smart Caching - Efficient data transfer with intelligent response limiting

🛠️ 18 Powerful AI Tools

📁 File System Tools

• get_file_tree - Complete project hierarchy with scripts, models, folders
• search_files - Find files by name, type, or content patterns

🎯 Studio Context Tools

• get_place_info - Place ID, name, game settings, workspace info
• get_services - All Roblox services and their child counts
• search_objects - Find instances by name, class, or properties

🔍 Instance & Property Tools

• get_instance_properties - Complete property dump for any object
• get_instance_children - Child objects with metadata (scripts, GUI types, etc.)
• search_by_property - Find objects with specific property values
• get_class_info - Available properties/methods for Roblox classes

⚡ Property Modification Tools

• set_property - Set a property on any Roblox instance
• mass_set_property - 🆕 NEW! Set the same property on multiple instances at once
• mass_get_property - 🆕 NEW! Get the same property from multiple instances at once

🏗️ Object Creation Tools

• create_object - Create a new Roblox object instance (basic)
• create_object_with_properties - 🆕 NEW! Create objects with initial properties
• mass_create_objects - 🆕 NEW! Create multiple objects at once (basic)
• mass_create_objects_with_properties - 🆕 NEW! Create multiple objects with properties
• delete_object - Delete a Roblox object instance

🏢 Project Analysis Tools

• get_project_structure - 🔥 ENHANCED! Smart hierarchy with improved depth control (recommended: depth 5-10)

⚠️ Note: Previous tools like get_file_content, get_file_properties, get_selection, get_dependencies, and validate_references have been removed. Use Rojo/Argon workflows or file system reading for better performance.

🧠 AI-Optimized Features

🚀 Mass Operations (NEW in v1.3.0)

• Bulk Property Editing: Set the same property on hundreds of instances instantly
• Mass Object Creation: Create complex object hierarchies with one call
• Batch Property Reading: Get properties from multiple objects efficiently
• Atomic Operations: All mass operations are grouped into single undo/redo waypoints

Example Use Cases:

1// Set all parts in workspace to red
2mass_set_property(["game.Workspace.Part1", "game.Workspace.Part2"], "BrickColor", "Really red")
3
4// Create 10 parts with properties
5mass_create_objects_with_properties([
6  {className: "Part", parent: "game.Workspace", name: "RedPart", properties: {BrickColor: "Really red"}},
7  {className: "Part", parent: "game.Workspace", name: "BluePart", properties: {BrickColor: "Really blue"}}
8])

Smart Project Structure

• Service Overview Mode: Clean service list with child counts
• Path-based Exploration: get_project_structure("game.ServerStorage", maxDepth=5)
• Script-only Filtering: scriptsOnly=true for code analysis
• Intelligent Grouping: Large folders auto-group by class type
• Enhanced Depth Control: Recommended maxDepth=5-10 for comprehensive exploration

Rich Metadata

• Script Status: Enabled/disabled, source detection, script types
• GUI Intelligence: Text content, visibility, container vs interactive
• Performance Optimized: Removed redundant tools for faster operation

🚀 Development & Testing

Commands

1npm run dev         # Development server with hot reload  
2npm run build       # Production build
3npm start           # Run built server
4npm run lint        # ESLint code quality
5npm run typecheck   # TypeScript validation

Plugin Development

• Live reload: Plugin updates automatically detect server changes
• Error handling: Robust timeout and retry mechanisms
• Debug mode: Detailed logging in Studio Output window
• Connection status: Visual indicators in plugin UI

📊 Communication Protocol

1%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#10b981', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#3b82f6', 'tertiaryColor':'#8b5cf6', 'background':'#1a202c', 'mainBkg':'#2d3748', 'secondBkg':'#374151', 'tertiaryColor':'#6366f1'}}}%%
2sequenceDiagram
3    participant AI as 🤖 AI Assistant
4    participant MCP as 📡 MCP Server  
5    participant HTTP as 🌐 HTTP Bridge
6    participant PLUGIN as 🎮 Studio Plugin
7    participant STUDIO as 🎯 Roblox Studio
8    
9    Note over AI,STUDIO: 🚀 Tool Request Flow
10    
11    AI->>+MCP: Call tool (e.g., get_file_tree)
12    MCP->>+HTTP: Queue request with UUID
13    HTTP->>HTTP: Store in pending requests map
14    HTTP-->>-MCP: Request queued ✅
15    
16    Note over PLUGIN: 🔄 Polling every 500ms
17    PLUGIN->>+HTTP: GET /poll
18    HTTP->>-PLUGIN: Return pending request + UUID
19    
20    PLUGIN->>+STUDIO: Execute Studio APIs
21    Note over STUDIO: 🎯 game.ServerStorage<br/>📋 Selection:Get()<br/>🔍 Instance properties
22    STUDIO->>-PLUGIN: Return Studio data 📊
23    
24    PLUGIN->>+HTTP: POST /response with UUID + data
25    HTTP->>-MCP: Resolve promise with data
26    MCP->>-AI: Return tool result 🎉
27    
28    Note over AI,STUDIO: ⚠️ Error Handling
29    
30    alt Request Timeout (30s)
31        HTTP->>MCP: Reject promise with timeout ⏰
32        MCP->>AI: Return error message ❌
33    end
34    
35    alt Plugin Disconnected
36        PLUGIN->>HTTP: Connection lost 🔌
37        HTTP->>HTTP: Exponential backoff retry 🔄
38        Note over PLUGIN: Status: "Waiting for server..." ⏳
39    end

Features:

• 🕐 30-second timeouts with exponential backoff
• 🔄 Automatic retries for network issues
• 📏 Response limiting prevents context overflow
• 🎯 Request deduplication for efficiency

🎯 Example Usage

1// Get service overview
2get_project_structure()
3
4// Explore weapons folder
5get_project_structure("game.ServerStorage.Weapons", maxDepth=2)
6
7// Find all Sound objects  
8search_by_property("ClassName", "Sound")
9
10// Check script dependencies
11get_dependencies("game.ServerScriptService.MainScript")
12
13// Find broken references
14validate_references()
15
16// Get UI component details
17get_instance_properties("game.StarterGui.MainMenu.SettingsFrame")

🔧 Configuration

Environment Variables:

• MCP_SERVER_PORT - MCP server port (default: stdio)
• HTTP_SERVER_PORT - HTTP bridge port (default: 3002)
• PLUGIN_POLL_INTERVAL - Plugin poll frequency (default: 500ms)
• REQUEST_TIMEOUT - Request timeout (default: 30000ms)

Studio Settings:

• ✅ Allow HTTP Requests (Game Settings → Security)
• 🌐 HttpService.HttpEnabled = true
• 🔌 Plugin activated via toolbar button

📋 Changelog

v1.3.0 - Mass Operations Update (Latest)

• ➕ NEW: mass_set_property - Bulk property modification
• ➕ NEW: mass_get_property - Batch property reading
• ➕ NEW: create_object_with_properties - Object creation with initial properties
• ➕ NEW: mass_create_objects - Bulk object creation
• ➕ NEW: mass_create_objects_with_properties - Bulk creation with properties
• 🔥 ENHANCED: get_project_structure with improved depth parameter documentation
• 🗑️ REMOVED: get_file_content, get_file_properties, get_selection, get_dependencies, validate_references (use Rojo/Argon workflows instead)
• ⚡ PERFORMANCE: Streamlined API with 18 focused tools vs 15 mixed-purpose tools

v1.2.0 - Property Modification

• ➕ Added set_property tool for instance modification
• ➕ Added create_object and delete_object tools
• 🔧 Enhanced error handling and validation

v1.1.0 - Enhanced Discovery

• 🔍 Improved project structure analysis
• 📊 Better metadata extraction
• 🎯 Script and GUI intelligence

📄 License

MIT License - Feel free to use in commercial and personal projects!