Roblox Studio MCP Server

MCP server for AI-powered Roblox Studio integration. 18 specialized tools for exploring projects, analyzing scripts, and performing bulk operations.

Quick Start

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:

   • Install from: https://create.roblox.com/store/asset/75577477776988
   • 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

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
• HTTP Bridge - Request/response queue on localhost:3002
• Studio Plugin (Luau) - Polls server and executes API calls
• Smart Caching - Efficient data transfer

18 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
• 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 - Set the same property on multiple instances
• mass_get_property - Get the same property from multiple instances

Object Creation Tools

• create_object - Create a new Roblox object instance
• create_object_with_properties - Create objects with initial properties
• mass_create_objects - Create multiple objects at once
• mass_create_objects_with_properties - Create multiple objects with properties
• delete_object - Delete a Roblox object instance

Project Analysis Tools

• get_project_structure - Smart hierarchy with depth control (recommended: 5-10)

Note: Previous tools removed: get_file_content, get_file_properties, get_selection, get_dependencies, validate_references. Use Rojo/Argon workflows instead.

AI-Optimized Features

Mass Operations (v1.3.0)

• Bulk property editing
• Mass object creation
• Batch property reading
• Atomic undo/redo operations

1// Example: Set multiple parts to red
2mass_set_property(["game.Workspace.Part1", "game.Workspace.Part2"], "BrickColor", "Really red")

Smart Project Structure

• Service overview with child counts
• Path-based exploration: get_project_structure("game.ServerStorage", maxDepth=5)
• Script-only filtering for code analysis
• Intelligent grouping for large folders
• Recommended maxDepth=5-10

Rich Metadata

• Script status tracking
• GUI intelligence
• Performance optimized

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
• Robust error handling
• Debug logging
• Visual status indicators

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
• Response limiting
• Request deduplication

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

License

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