npm package: @purplepiratepeep/rbx-mcp
Description: MCP Server for Roblox Studio - AI agent bridge with WebSocket, multi-session, multi-place support
Latest version: 2.0.2

# 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.

![Screenshot](screenshot.png)

## 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`):

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

## Development

```bash
# 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