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:

MCP Server (src/index.ts) - A Node.js server that implements the MCP protocol and communicates with AI clients
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

Open Roblox and join a game
Open your script executor
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