Skip to main content
Glama

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.

Available Tools

4 tools
get_propertiesC

Get properties of a Roblox instance

Inputs: path (required), properties.

list_childrenC

List children of a Roblox instance

Inputs: path.

read_scriptA

Read the source code of a script (decompiles if necessary). Note: Cannot read server-side scripts (Script) from a client execution context as their source is not replicated.

Inputs: path (required).

run_scriptC

Execute arbitrary Lua code in the Roblox client

Inputs: code (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: get_properties retrieves instance attributes, list_children enumerates child objects, read_script accesses script source code, and run_script executes Lua code. There is no overlap in functionality, making tool selection unambiguous for an agent.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_properties, list_children, read_script, run_script) using snake_case. The naming is predictable and readable, with no deviations in style or convention.

    Tool Count4/5

    With 4 tools, the count is reasonable for a Roblox-focused server, covering core operations like inspection and execution. However, it feels slightly thin, as additional tools for actions like modifying instances or handling events could enhance coverage without being excessive.

    Completeness3/5

    The tools provide good read/execute capabilities for Roblox instances and scripts, but there are notable gaps in write operations (e.g., no create, update, or delete tools). This limits agents to inspection and execution without full lifecycle management, which may cause workarounds for more complex tasks.

    Related MCP Connectors