Roblox MCP Server
Enables AI assistants to inspect the Roblox game hierarchy, read client-side script source code, retrieve instance properties, and execute Lua code directly within a running Roblox client through a WebSocket bridge.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Roblox MCP Server list the children in Workspace and show me any scripts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 <--> GameThe system consists of two parts:
MCP Server (
src/): A Node.js application that implements the MCP specification. It hosts a WebSocket server to communicate with Roblox.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 compatibleWebSocketlibrary).getgenv()(optional, for safe environment access).decompile(optional, for reading local scripts).
npm or yarn.
Installation
Clone the repository.
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 startThe server will start listening on stdio for MCP connections and ws://localhost:3000 for the Roblox bridge.
2. Inject the Roblox Bridge
Open your Roblox Executor.
Open
roblox/Bridge.lua.Execute the script in the desired Roblox game instance.
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
LocalScriptandModuleScript(client-side).Cannot read server-side
Scriptsource 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
3000is free and the executor supports WebSockets (most modern ones do).Executor Compatibility: If
WebSocketis not defined, check your executor's documentation. You may need a polyfill.
Available Tools
4 toolsget_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
Scored across 4 tools
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.
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.
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.
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
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Live browser debugging for AI assistants — DOM, console, network via MCP.