README.md
AI-powered Roblox Studio integration for project exploration and editing
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/Pluginsfolder
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 AssistantClaude Code/Desktop"]
MCP["MCP ServerNode.js + TypeScript"]
end
subgraph COMM_LAYER ["Communication Layer"]
HTTP["HTTP Bridgelocalhost:3002"]
QUEUE["Request QueueUUID tracking"]
end
subgraph STUDIO_ENV ["Roblox Studio Environment"]
PLUGIN["Studio PluginLuau Script"]
STUDIO["Roblox StudioAPIs & Data"]
end
subgraph TOOLS ["37+ AI Tools"]
FILE["File SystemTrees, Search"]
CONTEXT["Studio ContextServices, Objects"]
PROPS["PropertiesGet, Set, Mass Ops"]
CREATE["Object CreationSingle, Mass, Properties"]
PROJECT["Project AnalysisSmart 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 localh
Tools (4)
explore_projectExplore the project hierarchy and services within Roblox Studio.edit_scriptModify the contents of a script file within the project.manage_attributesGet or set attributes for specific objects in the scene.bulk_manipulationPerform bulk operations on multiple objects simultaneously.Configuration
claude_desktop_config.json
{"mcpServers": {"robloxstudio-mcp": {"command": "npx", "args": ["-y", "robloxstudio-mcp"]}}}Try it
→List all objects currently in the Workspace and their properties.
→Find all scripts in the project that contain the word 'Damage' and update them to use the new API.
→Create a new Part in the Workspace and set its color to red and transparency to 0.5.
→Bulk rename all parts in the 'Environment' folder to include the prefix 'Env_'.
→Check the attributes of the 'GameManager' object and report any missing values.