Roblox MCP Server

A Model Context Protocol (MCP) server that bridges AI assistants with Roblox via a Lua client. This enables AI tools like Claude to interact with the Roblox game environment in real-time.

Overview

This project consists of two components:

1. MCP Server (src/index.ts) - A Node.js server that implements the MCP protocol and communicates with AI clients
2. Lua Client (client.lua) - A Lua script that runs inside Roblox via a script executor and connects to the MCP server via WebSocket

Prerequisites

• Node.js v18 or higher
• npm or yarn
• A Roblox script executor with WebSocket support (e.g., Synapse X, KRNL, Fluxus, Solara)

Installation

1. Clone and Install Dependencies

cd mcp
npm install

2. Build the Server

npm run build

This compiles the TypeScript source to JavaScript in the build/ directory.

Configuration

MCP Client Configuration (Claude Desktop, etc.)

Add the following to your MCP client configuration file:

Claude Desktop (Windows)

Location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "roblox": {
      "command": "node",
      "args": ["C:/path/to/mcp/build/index.js"]
    }
  }
}

Claude Desktop (macOS)

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roblox": {
      "command": "node",
      "args": ["/path/to/mcp/build/index.js"]
    }
  }
}

WebSocket Port

The server listens on port 8888 by default. You can modify this in src/index.ts if needed.

Usage

Step 1: Start the MCP Server

The MCP server starts automatically when your AI client (like Claude Desktop) initializes it. Alternatively, for testing:

npm start

Step 2: Connect the Lua Client

1. Open Roblox and join a game
2. Open your script executor
3. Copy the contents of client.lua and execute it

The client will automatically:

• Connect to the WebSocket server at ws://localhost:8888
• Forward game logs to the MCP server
• Handle commands from the AI assistant
• Auto-reconnect if disconnected

Tip: Add client.lua to your executor's autoexec folder for automatic connection on startup.

Available Tools

The MCP server exposes the following tools that AI assistants can use:

Instance Navigation

Tool	Description
get_children	Get children of an instance (default: game)
find_instances	Search for instances by name pattern or ClassName
get_properties	Get properties and attributes of an instance
get_hidden_properties	Get hidden/internal properties using executor functions

Script Operations

Tool	Description
read_script	Read/decompile the source code of a script
execute_script	Execute Lua code in the Roblox context

Remote Spy

Tool	Description
remote_spy_start	Start monitoring RemoteEvent/RemoteFunction calls
remote_spy_stop	Stop the remote spy
remote_spy_get_logs	Get collected remote spy logs
fire_remote	Fire a RemoteEvent or invoke a RemoteFunction

Advanced/Debug

Tool	Description
getgc_find	Search Lua garbage collector for functions/tables
get_connections	Get all connections on an event/signal
get_upvalues	Get upvalues of a function

Tool Examples

Get Children of Workspace

Use get_children with path "game.Workspace"

Find All Parts

Use find_instances with query "" and className "Part"

Read a Script

Use read_script with path "game.ReplicatedStorage.SomeModule"

Execute Code

Use execute_script with code "print(game.Players.LocalPlayer.Name)"

Monitor Remotes

1. Use remote_spy_start (optionally with filter "Shop")
2. Play the game normally
3. Use remote_spy_get_logs to see captured calls
4. Use remote_spy_stop when done

Fire a Remote

Use fire_remote with path "game.ReplicatedStorage.MyRemote" and args ["hello", 123]

Executor Compatibility

The Lua client checks for WebSocket support from various executors:

• ✅ Synapse X (syn.websocket)
• ✅ KRNL (WebSocket)
• ✅ Fluxus (fluxus.websocket)
• ✅ Solara (WebSocket)
• ✅ Any executor with global WebSocket

Some advanced features require additional executor functions:

Feature	Required Function
Script decompilation	decompile()
Remote spy	hookmetamethod()
GC search	getgc(), getinfo()
Get connections	getconnections()
Get upvalues	getupvalues()
Hidden properties	gethiddenproperty()

Development

Run in Development Mode

npm run dev

Build

npm run build

Project Structure

mcp/
├── src/
│   └── index.ts      # MCP server source
├── build/
│   └── index.js      # Compiled server
├── client.lua        # Roblox Lua client
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

"No Lua client connected"

• Make sure you've executed client.lua in your Roblox executor
• Check that the WebSocket port (8888) is not blocked by firewall
• Verify your executor supports WebSocket

"Port 8888 is already in use"

Another instance of the server is running. Kill it or restart your computer.

"WebSocket not supported on this executor"

Your executor doesn't have WebSocket support. Try a different executor.

Connection drops frequently

The client auto-reconnects after 5 seconds. If issues persist, check your network or executor stability.

Security Notice

⚠️ This tool is intended for educational and development purposes only. Using script executors may violate Roblox's Terms of Service and could result in account termination.

License

ISC