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.luaand 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.luain 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