robloxstudio-mcp

You can install the plugin using one of three methods depending on your preference:

Method 1: Roblox Creator Store (Easiest)

1. Visit the Creator Store asset page.
2. Click "Install".
3. The plugin will automatically open in Roblox Studio.

Method 2: Direct Download

1. Download the official MCPPlugin.rbxmx from the latest GitHub Release.
2. Place the file in your local plugins folder:
   • Windows: %LOCALAPPDATA%/Roblox/Plugins/
   • macOS: ~/Documents/Roblox/Plugins/
   • Alternatively: In Studio, go to the Plugins tab > Plugins Folder and drop the file there.
3. Restart Roblox Studio.

Method 3: Save as Local Plugin

1. Copy the source code from plugin.server.luau.
2. In Roblox Studio, create a new Script in ServerScriptService and paste the code.
3. Right-click the script and select "Save as Local Plugin...".
4. Name it "Roblox Studio MCP".

Before the plugin can function, you must complete these configuration steps:

1. Enable HTTP Requests

In Roblox Studio, navigate to Game Settings > Security and enable "Allow HTTP Requests". This is required for the plugin to communicate with the MCP server.

2. Activate the Plugin

Go to the Plugins toolbar and click the "MCP Server" button.

• Green status: Connected and ready.
• Red status: Disconnected (this is normal until the MCP server is running).

3. Install the MCP Server

Depending on your AI assistant, run the appropriate command or configuration:

For Claude Code:

claude mcp add robloxstudio-mcp

For Claude Desktop or other MCP clients: Add the following to your mcpServers configuration:

{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "npx",
      "args": ["-y", "robloxstudio-mcp"]
    }
  }
}

Note for Windows users: If you encounter issues, use cmd to wrap the execution:

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

The RobloxStudioTools class includes a powerful system for creating, saving, and importing procedural builds (collections of parts) using a local JSON library.

Build Library Location

The library is stored in a build-library directory. It searches in this order:

1. Path specified by ROBLOXSTUDIO_MCP_BUILD_LIBRARY or BUILD_LIBRARY_PATH env vars.
2. The project root (where .git or package.json is found).
3. The current working directory.
4. The user's home directory (~/.robloxstudio-mcp/build-library).

Key Build Operations

• createBuild(id: string, style: string, palette: Record<string, any>, parts: unknown, bounds?: [number, number, number]): Manually saves a collection of parts as a build file.
• generateBuild(id: string, style: string, palette: Record<string, [string, string]>, code: string, seed?: number): Runs a procedural generator (via runBuildExecutor) and saves the resulting parts to the library.
• importBuild(buildData: Record<string, any> | string, targetPath: string, position?: [number, number, number]): Imports a build from the library into the game. buildData can be the full object or just the id string.
• listLibrary(style?: string): Lists all available builds in the library, optionally filtered by style (e.g., 'medieval', 'scifi').
• getBuild(id: string): Retrieves metadata and the palette for a specific build ID.

// Generate a new build using procedural code
await tools.generateBuild(
  'forest_patch_01',
  'nature',
  { grass: ['Green', 'Grass'] },
  'return generateTree(palette);',
  12345
);

// Import a saved build into the Workspace
await tools.importBuild('forest_patch_01', 'game.Workspace', [0, 10, 0]);

The RobloxStudioMCPServer operates in two distinct modes to ensure connectivity between the MCP client and the Roblox Studio plugin:

1. Primary Mode: The server successfully binds to the designated port (default 58741 or via ROBLOX_STUDIO_PORT). It hosts an HTTP server that the Roblox Studio plugin connects to directly. This is the preferred mode for low-latency communication.
2. Proxy Mode: If the primary ports are already in use, the server enters proxy mode. It initializes a ProxyBridgeService that forwards requests to a local address (default http://localhost:${basePort}). It will periodically attempt to "promote" itself back to Primary mode if the ports become available.

Environment Variables

Connection Monitoring

The server monitors the connection status between the Studio plugin and the MCP server. It logs warnings if the plugin is connected but the MCP server is inactive, or if the MCP server is active but no plugin is detected.

The Build Library allows for efficient, token-optimized creation of complex models.

Core Workflow

1. Generate/Create: Use generate_build (procedural JS) or create_build (manual parts) to define a model. These are saved to the local library.
2. Export: Use export_build to convert existing Studio models/folders into the compact JSON format.
3. Import: Use import_build to place a model into the game. You can pass a full buildData object or a library id (e.g., "medieval/cottage_01").

Procedural Generation with generate_build

When using generate_build, always generate the entire scene in one call. Use high-level primitives to maximize efficiency:

• room(x,y,z, w,h,d, wallKey, floorKey?, ceilKey?, wallThickness?)
• roof(x,y,z, w,d, style, key, overhang?)
• stairs(x1,y1,z1, x2,y2,z2, width, key)
• column(x,y,z, height, radius, key, capKey?)
• pew(x,y,z, w,d, seatKey, legKey?)
• arch(x,y,z, w,h, thickness, key, segments?)
• fence(x1,z1, x2,z2, y, key, postSpacing?)

Important: When modifying an existing build, always call get_build first to retrieve the original code, then make only the targeted changes. Never rewrite the entire code from scratch.

Build Library Management

• list_library: Lists available builds, optionally filtered by style (medieval, modern, nature, scifi, misc).
• get_build: Retrieves metadata, palette, and generator code for a specific build ID.
• import_scene: Imports a full layout containing multiple models and placement data.
• search_materials: Finds MaterialVariant names in MaterialService to use in your build palettes.

// Example: compact cabin generation
room(0,0,0,8,4,6,"a","b","a")
roof(0,4,0,8,6,"gable","c")
wall(-4,0,-2,4,0,-2,4,1,"a")
part(0,2,3,3,3,0.3,"a","Block",0.4)
row(-2,0,-1,3,0,2,(i,cx,cy,cz)=>{pew(cx,0,cz,3,2,"d")})
column(-3,0,-2,4,0.5,"a","b")
column(3,0,-2,4,0.5,"a","b")
part(0,2,0,2,1,1,"b")