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

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:

   npm install

Usage

1. Start the MCP Server

You can run the server in development mode or build it for production.

Development:

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