rbx-mcp

MCP (Model Context Protocol) Server for Roblox Studio — an AI agent bridge that enables AI assistants to interact with Roblox Studio in real time via WebSocket.

Features

• 80+ MCP Tools — Full control over Roblox Studio: instances, scripts, properties, attributes, tags, camera, playtest, DataStores, and more.
• Multi-Place Support — Connect multiple Studio instances simultaneously and switch between them.
• Multi-Session — Handle concurrent MCP sessions with request queuing and timeout management.
• Rojo Mode — Safely disable script writes when using Rojo file sync to prevent conflicts.
• Luau Linting — Built-in selene integration for linting scripts and raw Luau source code.
• Screenshot Capture — Capture the Studio viewport as PNG directly from edit mode.
• DataStore Access — Read, write, list, and delete DataStore keys with a safety toggle.
• Playtest Control — Start and stop playtest sessions programmatically.
• Undo/Redo — Full ChangeHistoryService integration.

Install the Studio Plugin

1. Open Roblox Studio.
2. Go to Plugins > Plugins Folder.
3. Copy the studio-plugin/MCPPlugin.rbxmx file to the folder and reload studio.
4. The plugin widget will appear with connection controls.

Configure Your MCP Client

Add to your MCP client configuration (e.g. .cursor/mcp.json):

{
  "mcpServers": {
    "rbx-mcp": {
      "command": "npx",
      "args": ["-y", "@purplepiratepeep/rbx-mcp"]
    }
  }
}

Development

# Run in development mode (with hot reload via tsx)
npm run dev

# Build TypeScript
npm run build

# Build the Studio plugin (.rbxmx)
npm run build:plugin

# Build everything
npm run build:all

# Type-check without emitting
npm run typecheck

Environment Variables

| Variable | Default | Description | |---|---|---| | ROBLOX_MCP_PORT | 3030 | WebSocket server port | | ROBLOX_MCP_HOST | 0.0.0.0 | WebSocket server host |

API Reference

All 68 MCP tools exposed by rbx-mcp, organized by category.

Place Management

| Tool | Description | |---|---| | list_connected_places | List all Studio places currently connected to the MCP server. Returns placeId, placeName, gameId, experienceName, rojoMode, and which one is selected. | | select_place | Select which connected Studio place to target. Required when multiple places are connected. | | get_place_info | Get place name, placeId, gameId, experienceName, and workspace info. | | get_game_settings | Get game settings: HttpEnabled, DataStore accessibility, Studio mode, placeId, gameId, experienceName. | | get_services | List available Roblox services and their children, or query a specific service. |

Instance Hierarchy & Search

| Tool | Description | |---|---| | get_file_tree | Get the instance hierarchy tree from Studio. Uses dot notation paths (e.g. game.Workspace). | | get_instance_children | Get child instances and their class types. | | get_instance_properties | Get all properties of an instance. Complex types are returned as structured objects with a _type field. | | get_project_structure | Get game project structure with optional depth limit and scripts-only filter. | | get_class_info | Get available properties/methods for a Roblox class. | | search_files | Search for instances by name, class type, or script content. | | search_objects | Find instances by name, class, or property value. | | search_by_property | Find all objects with a specific property value. | | get_descendants_count | Count all descendants under a path and return a breakdown of the top 25 classes by count. |

Properties

| Tool | Description | |---|---| | set_property | Set a property on an instance. Supports complex types via structured objects (UDim2, Vector3, Color3, CFrame, etc.). | | mass_set_property | Set the same property on multiple instances at once. | | mass_get_property | Get the same property from multiple instances. | | set_relative_property | Modify a property relative to its current value (add, subtract, multiply, divide, power). Supports Vector3/UDim2 components. | | set_calculated_property | Set a property using a formula expression with variables. |

Object Operations

| Tool | Description | |---|---| | create_object | Create a new Roblox instance with optional initial properties. | | mass_create_objects | Create multiple instances in one call. | | delete_object | Delete a Roblox instance. | | mass_delete | Delete all instances matching criteria (name, class, or tag). Supports dry run preview. | | smart_duplicate | Duplicate an instance with naming patterns, position/rotation/scale offsets, and property variations. | | mass_duplicate | Duplicate multiple instances with individual options. | | move_instance | Move/reparent an instance to a new parent. Preserves all children and properties. | | rename_instance | Rename one or more instances. Supports {n} placeholder for sequential numbering. | | group_instances | Group multiple instances into a new Model or Folder container. | | ungroup_instances | Ungroup a container by moving all children to its parent, then destroying it. | | clone_instance | Create a lightweight clone of an instance. | | set_locked | Lock or unlock BasePart instances. When given a non-BasePart, locks/unlocks all BasePart descendants. |

Script Editing

| Tool | Description | |---|---| | get_script_source | Get source code of a Script, LocalScript, or ModuleScript. Optional line range. | | set_script_source | Replace the entire source code of a script. | | edit_script_lines | Replace specific lines in a script. | | insert_script_lines | Insert lines after a specific line number. | | delete_script_lines | Delete a range of lines from a script. | | find_replace_in_scripts | Find and replace text across all scripts under a scope. Supports regex and dry run mode. | | get_script_dependencies | Trace require() dependency chains from a script or across all scripts. |

Attributes

| Tool | Description | |---|---| | get_attribute | Get a single attribute value from an instance. | | set_attribute | Set an attribute on an instance. Supports valueType hint for complex types. | | get_attributes | Get all attributes on an instance. | | delete_attribute | Delete an attribute from an instance. |

Tags (CollectionService)

| Tool | Description | |---|---| | get_tags | Get all CollectionService tags on an instance. | | add_tag | Add a CollectionService tag to an instance. | | remove_tag | Remove a CollectionService tag from an instance. | | get_tagged | Get all instances with a specific tag. |

Selection

| Tool | Description | |---|---| | get_selection | Get currently selected instances in Studio. | | set_selection | Set the currently selected instances in Studio. |

Undo / Redo

| Tool | Description | |---|---| | undo | Undo the last action (ChangeHistoryService). | | redo | Redo the last undone action (ChangeHistoryService). |

Output & Execution

| Tool | Description | |---|---| | get_output_logs | Get recent output/log messages from Studio. Filterable by text and message type. | | execute_luau | Execute arbitrary Luau code in Studio and return the result. Runs in the plugin context with full access to game services. |

Performance & Diagnostics

| Tool | Description | |---|---| | get_performance_stats | Get memory usage, total instance count, physics FPS, heartbeat delta time, and gravity. | | get_descendants_count | Count descendants and return a class breakdown. Useful for auditing instance bloat. |

Remotes

| Tool | Description | |---|---| | list_remotes | Find all RemoteEvents, RemoteFunctions, BindableEvents, BindableFunctions, and UnreliableRemoteEvents. |

Playtest

| Tool | Description | |---|---| | start_playtest | Start a playtest session. Mode can be play (solo with player) or run (server only). | | stop_playtest | Stop the currently running playtest session. Must be called from the server connection. | | is_playtest_running | Check if a playtest is running. Returns running state and connection type. | | get_server_events | Get recent server events (place connected/disconnected). Supports polling via timestamp. |

Camera

| Tool | Description | |---|---| | set_camera | Set camera position and orientation. Accepts position+lookAt or a full CFrame, plus optional FOV. | | focus_camera | Focus/zoom the camera on an instance. Auto-calculates viewing angle from bounding box. |

Screenshot

| Tool | Description | |---|---| | capture_screenshot | Capture the Studio viewport as a PNG. Works in edit mode. Configurable resolution with optional save-to-disk. |

Constraints

| Tool | Description | |---|---| | create_constraint | Create a physics constraint between two parts with automatic Attachment setup. Supports WeldConstraint, HingeConstraint, RopeConstraint, SpringConstraint, and more. |

DataStore

| Tool | Description | |---|---| | datastore_get | Read a key from a DataStore. Requires API services enabled and DataStore Access toggle on. | | datastore_set | Write a key to a DataStore. WARNING: writes to the live experience DataStore. | | datastore_list_keys | List keys in a DataStore with optional prefix filter. | | datastore_delete | Remove a key from a DataStore. WARNING: deletes from the live experience DataStore. |

Linting

| Tool | Description | |---|---| | lint_script | Lint a script in Studio using selene (auto-downloaded on first use). | | lint_source | Lint raw Luau source code using selene. Does not require a Studio connection. |

Studio Plugin Features

The Roblox Studio plugin provides:

• Connection Widget — UI for managing the WebSocket connection with status indicator.
• Auto-Reconnect — Exponential backoff reconnection on disconnect.
• Rojo Mode Toggle — Prevents script source modifications when Rojo is active.
• DataStore Access Toggle — Explicit opt-in for DataStore operations (accesses live data).
• Activity History — Recent operations displayed in the widget.
• Toast Notifications — Non-intrusive feedback on operations.
• Type Serialization — Handles Vector3, CFrame, Color3, UDim2, BrickColor, and other Roblox types.

License

MIT