Roblox Studio MCP Server (Enhanced Fork)

Fork of boshyxd/robloxstudio-mcp — the original MCP server for Roblox Studio created by @boshyxd.

This fork (v2.0.0) adds significant improvements: long polling instead of 500ms interval polling, 16 new tools, Vector3 property fix, enhanced activity logger with copy/export, and a battle-tested plugin for complex Roblox projects.

MCP server for AI-powered Roblox Studio integration. 37+ specialized tools for exploring projects, editing scripts, manipulating attributes/tags, and performing bulk operations.

What's new in this fork

Feature	Original	This Fork
Polling	500ms interval polling	Long polling (instant response)
Tools	37 tools	37+ tools + 16 new ones
Vector3 properties	Broken on mass operations	Fixed (`{"X":n,"Y":n,"Z":n}` format)
Activity logger	None	Full UI logger with copy/export
Plugin UI	Basic status	Enhanced status + activity panel

Quick Start

For Claude Code users:

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

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

{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "npx",
      "args": ["-y", "robloxstudio-mcp"],
      "description": "Advanced Roblox Studio integration for AI assistants"
    }
  }
}

Install NPM Package

npm i robloxstudio-mcp

Note for native Windows users

If you encounter issues, you may need to run it through `cmd`. Update your configuration like this:

{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "robloxstudio-mcp@latest"]
    }
  }
}

Studio Plugin Setup (Required)

The MCP server requires a companion Roblox Studio plugin:

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

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:

%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#718096', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#2b6cb0', 'tertiaryColor':'#319795'}}}%%
graph TB
    subgraph AI_ENV ["AI Environment"]
        AI["AI Assistant<br/>Claude Code/Desktop"]
        MCP["MCP Server<br/>Node.js + TypeScript"]
    end
    
    subgraph COMM_LAYER ["Communication Layer"]
        HTTP["HTTP Bridge<br/>localhost:3002"]
        QUEUE["Request Queue<br/>UUID tracking"]
    end
    
    subgraph STUDIO_ENV ["Roblox Studio Environment"]
        PLUGIN["Studio Plugin<br/>Luau Script"]
        STUDIO["Roblox Studio<br/>APIs & Data"]
    end
    
    subgraph TOOLS ["37+ AI Tools"]
        FILE["File System<br/>Trees, Search"]
        CONTEXT["Studio Context<br/>Services, Objects"]
        PROPS["Properties<br/>Get, Set, Mass Ops"]
        CREATE["Object Creation<br/>Single, Mass, Properties"]
        PROJECT["Project Analysis<br/>Smart Structure"]
    end
    
    AI -->|stdio| MCP
    MCP -->|HTTP POST| HTTP
    HTTP -->|Queue Request| QUEUE
    PLUGIN -->|Poll every 500ms| HTTP
    HTTP -->|Pending Work| PLUGIN
    PLUGIN -->|Execute APIs| STUDIO
    STUDIO -->|Return Data| PLUGIN
    PLUGIN -->|HTTP Response| HTTP
    HTTP -->|Resolve Promise| MCP
    MCP -->|Tool Result| AI
    
    MCP -.->|Exposes| FILE
    MCP -.->|Exposes| CONTEXT  
    MCP -.->|Exposes| PROPS
    MCP -.->|Exposes| CREATE
    MCP -.->|Exposes| PROJECT
    
    classDef aiStyle fill:#1e40af,stroke:#3b82f6,stroke-width:2px,color:#ffffff
    classDef mcpStyle fill:#7c3aed,stroke:#8b5cf6,stroke-width:2px,color:#ffffff
    classDef httpStyle fill:#ea580c,stroke:#f97316,stroke-width:2px,color:#ffffff
    classDef pluginStyle fill:#059669,stroke:#10b981,stroke-width:2px,color:#ffffff
    classDef studioStyle fill:#dc2626,stroke:#ef4444,stroke-width:2px,color:#ffffff
    classDef toolStyle fill:#0891b2,stroke:#06b6d4,stroke-width:2px,color:#ffffff
    
    class AI aiStyle
    class MCP mcpStyle
    class HTTP,QUEUE httpStyle
    class PLUGIN pluginStyle
    class STUDIO studioStyle
    class FILE,CONTEXT,PROPS,CREATE,PROJECT toolStyle

Key Components:

MCP Server (Node.js/TypeScript) - Exposes 37+ tools via stdio and HTTP
HTTP Bridge - Request/response queue on localhost:3002
Studio Plugin (Luau) - Polls server and executes API calls
Full HTTP API - All tools available via both stdio MCP and HTTP endpoints

37+ 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
get_selection - Get currently selected objects in Studio

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
set_calculated_property - Set properties using mathematical formulas
set_relative_property - Modify properties relative to current values

Object Creation & Manipulation 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
smart_duplicate - Duplicate with naming patterns, position offsets, property variations
mass_duplicate - Perform multiple smart duplications at once

Script Editing Tools (v1.9.0)

get_script_source - Read script source code with line numbers
set_script_source - Replace entire script source
edit_script_lines - Replace specific lines without rewriting entire script
insert_script_lines - Insert new lines at specific positions
delete_script_lines - Delete specific lines from scripts

Attribute Tools (v1.9.0)

get_attribute - Get a single attribute value
set_attribute - Set an attribute (supports Vector3, Color3, etc.)
get_attributes - Get all attributes on an instance
delete_attribute - Remove an attribute

Tag Tools (CollectionService) (v1.9.0)

get_tags - Get all tags on an instance
add_tag - Add a tag to an instance
remove_tag - Remove a tag from an instance
get_tagged - Find all instances with a specific tag

Project Analysis Tools

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

AI-Optimized Features

Mass Operations (v1.3.0)

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

// Example: Set multiple parts to red
mass_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

npm run dev         # Development server with hot reload
npm run build       # Production build
npm start           # Run built server
npm run lint        # ESLint code quality
npm run typecheck   # TypeScript validation
npm test            # Run Jest unit tests
npm run test:e2e    # Run Lune E2E tests (requires server running)
npm run test:all    # Run all tests

Testing

Jest Unit Tests - 32 tests covering bridge service, HTTP server, and integration
Lune E2E Tests - 30 tests verifying all HTTP endpoints work correctly
Tests ensure full feature parity between stdio MCP and HTTP modes

Plugin Development

Live reload
Robust error handling
Debug logging
Visual status indicators

Communication Protocol

%%{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'}}}%%
sequenceDiagram
    participant AI as AI Assistant
    participant MCP as MCP Server  
    participant HTTP as HTTP Bridge
    participant PLUGIN as Studio Plugin
    participant STUDIO as Roblox Studio
    
    Note over AI,STUDIO: Tool Request Flow
    
    AI->>+MCP: Call tool (e.g., get_file_tree)
    MCP->>+HTTP: Queue request with UUID
    HTTP->>HTTP: Store in pending requests map
    HTTP-->>-MCP: Request queued
    
    Note over PLUGIN: Polling every 500ms
    PLUGIN->>+HTTP: GET /poll
    HTTP->>-PLUGIN: Return pending request + UUID
    
    PLUGIN->>+STUDIO: Execute Studio APIs
    Note over STUDIO: game.ServerStorage<br/>Selection:Get()<br/>Instance properties
    STUDIO->>-PLUGIN: Return Studio data
    
    PLUGIN->>+HTTP: POST /response with UUID + data
    HTTP->>-MCP: Resolve promise with data
    MCP->>-AI: Return tool result
    
    Note over AI,STUDIO: Error Handling
    
    alt Request Timeout (30s)
        HTTP->>MCP: Reject promise with timeout
        MCP->>AI: Return error message
    end
    
    alt Plugin Disconnected
        PLUGIN->>HTTP: Connection lost
        HTTP->>HTTP: Exponential backoff retry
        Note over PLUGIN: Status: "Waiting for server..."
    end

Features:

30-second timeouts with exponential backoff
Automatic retries
Response limiting
Request deduplication

Example Usage

// Get service overview
get_project_structure()

// Explore weapons folder
get_project_structure("game.ServerStorage.Weapons", maxDepth=2)

// Find all Sound objects  
search_by_property("ClassName", "Sound")

// Check script dependencies
get_dependencies("game.ServerScriptService.MainScript")

// Find broken references
validate_references()

// Get UI component details
get_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!

Roblox Studio MCP Server