# Roblox MCP Server
A Model Context Protocol (MCP) server that acts as a bridge between AI assistants (like Claude/Gemini in IDEs) and a running Roblox instance. This allows the AI to inspect the game hierarchy, read scripts, and execute code directly within the Roblox client.
## Architecture
```mermaid
graph LR
IDE["AI / IDE"] <-->|"MCP Protocol (Stdio)"| MCPServer["MCP Server (Node.js)"]
MCPServer <-->|"WebSocket (ws://localhost:3000)"| Roblox["Roblox Client"]
subgraph Roblox Client
Bridge["Bridge.lua"]
Game["Game Engine"]
end
Bridge <--> Game
```
The system consists of two parts:
1. **MCP Server (`src/`)**: A Node.js application that implements the MCP specification. It hosts a WebSocket server to communicate with Roblox.
2. **Roblox Bridge (`roblox/Bridge.lua`)**: A Lua script that runs inside a Roblox executor. It connects to the MCP server via WebSocket and executes commands.
## Prerequisites
* **Node.js**: v18 or higher.
* **Roblox Executor**: A Roblox script executor that supports:
* `WebSocket.connect` (or compatible `WebSocket` library).
* `getgenv()` (optional, for safe environment access).
* `decompile` (optional, for reading local scripts).
* **npm** or **yarn**.
## Installation
1. Clone the repository.
2. Install dependencies:
```bash
npm install
```
## Usage
### 1. Start the MCP Server
You can run the server in development mode or build it for production.
**Development:**
```bash
# Compile and run
npm run build && npm start
```
The server will start listening on `stdio` for MCP connections and `ws://localhost:3000` for the Roblox bridge.
### 2. Inject the Roblox Bridge
1. Open your Roblox Executor.
2. Open `roblox/Bridge.lua`.
3. Execute the script in the desired Roblox game instance.
4. Check the executor console (F9) for a connection message: `[MCP-Bridge] Connected!`.
## Available Tools
The MCP server exposes the following tools to the AI:
### `list_children`
Lists the children of a specific instance.
* **Arguments**: `path` (string, e.g., "game.Workspace")
* **Returns**: list of `{ name, className, path }`
### `get_properties`
Retrieves the properties of a specific instance.
* **Arguments**: `path` (string), `properties` (array of strings, optional)
* **Returns**: Map of property names to values.
### `read_script`
Reads the source code of a script.
* **Arguments**: `path` (string)
* **Returns**: Source code string.
* **Notes:**
* Works for `LocalScript` and `ModuleScript` (client-side).
* **Cannot** read server-side `Script` source due to Roblox replication security (returns empty/error).
### `run_script`
Executes arbitrary Lua code in the context of the bridge script.
* **Arguments**: `code` (string)
* **Returns**: Array of return values converted to strings.
## Troubleshooting
* **Server Code Access**: You cannot read server scripts from the client. This is a Roblox engine limitation, not a bug.
* **Connection Failed**: Ensure port `3000` is free and the executor supports WebSockets (most modern ones do).
* **Executor Compatibility**: If `WebSocket` is not defined, check your executor's documentation. You may need a polyfill.
