home / mcp / roblox mcp server

Roblox MCP Server

Bridges AI assistants with Roblox via a WebSocket MCP server and a Lua client for real-time game interaction.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "0xxrer-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/mcp/build/index.js"
      ],
      "env": {
        "YOUR_API_KEY": "ABC123",
        "WEB_SOCKET_PORT": "8888"
      }
    }
  }
}

You can connect AI assistants to Roblox in real time by running a dedicated MCP server that speaks the Model Context Protocol and a Lua client that hooks into Roblox. This setup lets you query and control Roblox game state from AI tools while keeping interactions synchronized with the game environment.

How to use

Start the MCP server locally and run the Lua client inside Roblox to establish a WebSocket bridge. The server listens for connections on port 8888. When the Lua client connects, it forwards game logs and responds to commands from your AI assistant. You can use the available tools to inspect game objects, read or execute scripts, monitor RemoteEvent/RemoteFunction activity, and perform debugging actions. If the connection drops, the client will automatically reconnect.

Typical usage patterns include: connecting the Lua client on startup, issuing commands to explore the Roblox hierarchy, reading script contents, executing small Lua snippets, and spying on remote calls to understand game behavior. For reliability, place the Lua client script in your executor’s autoexec folder so it reconnects automatically when Roblox starts.

How to install

Prerequisites: install Node.js version 18 or higher and a JavaScript package manager such as npm or yarn.

# 1) Install dependencies
cd mcp
npm install

# 2) Build the server
npm run build

# 3) Start the server
npm start

After building, the server runs from the build output. The Lua client remains the same and connects to ws://localhost:8888 once the server is running.

Configuration and usage notes

The MCP server uses WebSocket communications and exposes a default listening port of 8888. You can modify the port if needed by changing the server source and rebuilding.

Client configuration for AI tools is handled through the MCP client configuration files. You can direct the AI client to start the server process by invoking the appropriate runtime command (for example, npm start) so the MCP server runs in the background as the AI tool connects.

Troubleshooting and tips

No Lua client connected: ensure you have executed the Lua client inside Roblox and that the Roblox firewall or network allows WebSocket connections on port 8888.

Port in use: if port 8888 is already occupied, stop the other process or reboot and retry.

WebSocket not supported by your executor: verify that your Roblox script executor supports WebSocket connections. If not, try a different executor that provides WebSocket functionality.

Connection drops: the client auto-reconnects after a brief delay. If issues persist, check your network stability and executor reliability.

Security note: use this tool for development and education. Ensure you comply with Roblox Terms of Service and rely on appropriate permissions when connecting external control to Roblox games.

Available tools

get_children

Retrieve child instances of a given Roblox object to navigate the hierarchy.

find_instances

Search for Roblox instances by name pattern or ClassName.

get_properties

Fetch properties and attributes of a Roblox instance.

get_hidden_properties

Access hidden/internal properties via executor APIs.

read_script

Read or decompile the source of a Roblox script.

execute_script

Execute Lua code within the Roblox context.

remote_spy_start

Begin monitoring RemoteEvent/RemoteFunction calls.

remote_spy_stop

Stop monitoring remote calls.

remote_spy_get_logs

Retrieve captured remote spy logs.

fire_remote

Invoke a RemoteFunction or fire a RemoteEvent.

getgc_find

Search Lua garbage collector for functions or tables.

get_connections

List all connections on a given event or signal.

get_upvalues

Inspect upvalues of a function.