roblox-mcp-difz

A bridge between AI agents and Roblox. I built this MCP (Model Context Protocol) server so your AI can directly control Roblox, reverse engineer games, intercept networks, simulate inputs, and mess with the game state.

It works with any MCP-compatible AI client like Claude Code, Cursor, Windsurf, or whatever else you use.

I packed it with 150+ tools. It can traverse the DataModel, inspect properties, fire remotes, run raw Lua, hook functions, intercept network traffic, and simulate user input. Basically, if you can do it in an executor, the AI can do it now.

Table of Contents

• Quick Start

• Installation

• Executor Setup

• MCP Client Configuration

• Commands

• UNC Compatibility (Executor Support)

• Tools (106 tools in total)

• How It Actually Works

• Multi-Instance Support

• When Things Break (Troubleshooting)

• Environment Variables

• Programmatic API

• License

Related MCP server: dex-mcp

Quick Start

# 1. Install
npm install -g roblox-mcp-difz

# 2. Configure AI platform (Claude Code, Cursor, etc.)
rblx-mcp setup

# 3. Start the server
rblx-mcp start

# 4. Inject into Roblox (paste into executor)
loadstring(game:HttpGet("http://127.0.0.1:28429/mcp.lua"))()

Installation

Global install (recommended)

npm install -g roblox-mcp-difz

This installs two CLI aliases: rblx-mcp and roblox-mcp-difz.

Run without installing

npx roblox-mcp-difz

Install from source

git clone https://github.com/Difz25x/roblox-mcp-difz.git
cd roblox-mcp-difz
npm install
npm run build
npm start

Requirements

• Node.js >= 16.0.0

• Windows (for Roblox process management; the MCP server itself can run on any platform)

• A Roblox executor that supports UNC (Universal Compatibility) functions (e.g., Synapse, Script-Ware, Krnl, or any executor with WebSocket and loadstring support)

Executor Setup

1. Start the server

rblx-mcp start

The server prints a banner with the HTTP and WebSocket URLs.

2. Inject the client script

In your Roblox executor, run:

loadstring(game:HttpGet("http://127.0.0.1:28429/mcp.lua"))()

You can also fetch /mcp.luau (same content) if your executor prefers that extension.

3. Verify connection

The server logs the registration with the game name, place ID, and job ID. Use the check_unc_capabilities tool to verify which UNC functions your executor supports.

getgenv() Configuration

Override defaults by setting these before loading mcp.lua:

getgenv().MCP_HOST = "127.0.0.1"       -- default: 127.0.0.1
getgenv().MCP_PORT = 28429              -- default: 28429
getgenv().MCP_TRANSPORT = "auto"        -- "auto" | "ws" | "http"
getgenv().MCP_WORKER_ID = "my-worker"   -- unique ID for multi-instance

MCP Client Configuration

The server exposes the standard MCP protocol via HTTP POST at /mcp. Configure your AI client to use the URL http://localhost:28429/mcp.

Claude Code

Automatic:

rblx-mcp setup --ai claude-code

Manual (JSON — ~/.mcp.json):

{
  "mcpServers": {
    "roblox-mcp-difz": {
      "type": "http",
      "url": "http://localhost:28429/mcp"
    }
  }
}

Or use the CLI:

claude mcp add roblox-mcp-difz -s user --transport http http://localhost:28429/mcp

Claude Desktop

Automatic:

rblx-mcp setup --ai claude-desktop

Manual (JSON — ~/AppData/Roaming/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "roblox-mcp-difz": {
      "type": "http",
      "url": "http://localhost:28429/mcp"
    }
  }
}

Cursor

Automatic:

rblx-mcp setup --ai cursor

Manual (JSON — ~/.cursor/mcp.json):

{
  "mcpServers": {
    "roblox-mcp-difz": {
      "type": "http",
      "url": "http://localhost:28429/mcp"
    }
  }
}

Windsurf

Automatic:

rblx-mcp setup --ai windsurf

Manual (JSON — ~/.windsurf/mcp_config.json):

{
  "mcpServers": {
    "roblox-mcp-difz": {
      "type": "http",
      "url": "http://localhost:28429/mcp"
    }
  }
}

VS Code (Cline / Continue.dev)

Automatic:

rblx-mcp setup --ai vscode

Manual (JSON — ~/.vscode/mcp.json):

{
  "mcpServers": {
    "roblox-mcp-difz": {
      "type": "http",
      "url": "http://localhost:28429/mcp"
    }
  }
}

Commands

Endpoints

UNC Compatibility (Executor Support)

The client script (mcp.lua) uses Universal Compatibility (UNC) functions to communicate with the Roblox executor and interact with the game. Not all executors support every function. The table below lists every UNC function required, which tools depend on it, and whether a fallback exists.

37 unique UNC functions are used across the tool set.

Note: loadstring is the only hard requirement — every other UNC function has a graceful fallback. Use the check_unc_capabilities tool at runtime to see exactly what your executor supports.

Tools (106 tools in total)

This MCP server comes with over 100 tools. Below are some of the most commonly used tools. For the complete list and detailed descriptions, refer to src/tool-definitions.ts.

Note: There are 96 other tools covering GUI manipulation, instance cloning/destroying, camera control, mouse/keyboard simulation, metatable manipulation, closure inspection, and more!

How It Actually Works

┌──────────────────────────────────────────────────────────────────┐
│                            AI Client                             │
│  (Claude Code / Claude Desktop / Cursor / Windsurf / Cline /     │
│   Continue.dev / any MCP-compatible client)                      │
└─────────────────────────┬────────────────────────────────────────┘
                          │ MCP JSON-RPC 2.0 (HTTP POST /mcp)
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│                   Node.js MCP Server (:28429)                    │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────────┐  │
│  │ MCP Handler │  │ Queue Manager│  │ WebSocket Server (WS)   │  │
│  │ (JSON-RPC)  │──│ (Task Queue) │──│ /ws                     │  │
│  └─────────────┘  └──────────────┘  └───────────┬─────────────┘  │
│                                                 │                │
│  ┌─────────────┐  ┌──────────────┐              │                │
│  │Tool Defs    │  │Session Mgr   │              │                │
│  │(106 tools)  │  │(workers)     │              │                │
│  └─────────────┘  └──────────────┘              │                │
│                                                 │                │
│  ┌──────────────────────────────────────────────┐                │
│  │ Server-Side Tools (Process Manager)          │                │
│  │ get_roblox_processes, launch_roblox,         │                │
│  │ open_game, capture_roblox_screenshot,        │                │
│  │ get_roblox_versions                          │                │
│  └──────────────────────────────────────────────┘                │
└─────────────────────────────────────────────────┼────────────────┘
                                                  │ WebSocket
                                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│                    Roblox Executor (mcp.lua)                     │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────────┐  │
│  │ WS Client   │  │ Task Router  │  │ Handler Registry        │  │
│  │ (connect)   │──│ (wsPoll)     │──│ (106+ handlers)         │  │
│  └─────────────┘  └──────────────┘  └─────────────────────────┘  │
│                                           │                      │
│  ┌────────────────────────────────────────┘                      │
│  │  UNC Compatibility Layer                                      │
│  │  (getnilinstances, hookfunction, loadstring, getreg,          │
│  │   getgc, getconnections, firesignal, readfile, writefile,     │
│  │   gethiddenproperty, sethiddenproperty, getrawmetatable, ...) │
│  └───────────────────────────────────────────────────────────────┘
│                                                                  │
│                     Roblox DataModel                             │
│  (Players, Workspace, Lighting, ReplicatedStorage, CoreGui, ...) │
└──────────────────────────────────────────────────────────────────┘

Data Flow

1. AI Client sends MCP JSON-RPC (tool call) via HTTP POST to /mcp

2. MCP Handler validates the tool name and dispatches it

3. Server-side tools (process management, screenshots) execute directly in Node.js

4. Executor tools are queued in the Queue Manager and sent via WebSocket to all connected Roblox executors

5. mcp.lua receives the task, routes it to the correct handler, which interacts with the Roblox DataModel using UNC functions

6. Result flows back: executor -> WebSocket -> Queue Manager -> MCP Handler -> AI Client

Communication Protocol

Registration (executor -> server):

{
  "type": "register",
  "worker_id": "uuid-or-custom-id",
  "username": "PlayerName",
  "userId": 123456,
  "placeId": 987654321,
  "jobId": "abc-def-ghi",
  "placeName": "Game Name",
  "capabilities": { "total": 37, "supported": 35, "missing": ["someFunc"] }
}

Task (server -> executor):

{
  "type": "task",
  "id": "task-uuid",
  "tool": "execute_custom_luau",
  "args": { "code": "print('hello')" },
  "pid": 1234,
  "workerId": "target-worker"
}

Result (executor -> server):

{
  "type": "result",
  "id": "task-uuid",
  "data": { "success": true, "result": "hello" },
  "error": null,
  "pid": 1234
}

Multi-Instance Support

Each executor registers with a unique worker_id. Tools can target a specific Roblox instance by PID:

{
  "name": "get_roblox_processes",
  "arguments": {}
}
// Returns [{ pid: 1234, name: "RobloxPlayerBeta", windowTitle: "Game Name" }]

{
  "name": "execute_custom_luau",
  "arguments": {
    "pid": 1234,
    "code": "print('hello from instance 1234')"
  }
}

If no PID is specified, tasks are broadcast to ALL connected executors. To use multi-instance with custom IDs, set getgenv().MCP_WORKER_ID = "my-instance" before injecting mcp.lua.

UNC Compatibility Layer

The client script (mcp.lua) includes a full compatibility layer that adapts to the executor's available UNC functions. Every function has a fallback strategy:

Decompilation Chain

The script_decompiler tool automatically falls through three decompile services:

1. LuaExpert (api.lua.expert) — primary

2. Medal (medal.upio.dev) — fallback 1

3. Konstant (api.plusgiant5.com) — fallback 2

When Things Break (Troubleshooting)

Check UNC Capabilities

Always start by checking what your executor supports:

Tool: check_unc_capabilities

This returns a complete support matrix showing which of the 37 UNC functions your executor provides, making it immediately clear which tools will work and which will report errors.

"Attempt to call blacklisted function" Error

Some executors block certain UNC functions (especially hookfunction, getgc, getreg, loadstring with restricted environments).

Solutions:

1. Run check_unc_capabilities to identify which functions are blocked

2. Try a different identity_level (use identity 8 for maximum access):

   Tool: luau_code_executor
   Arguments: { "code": "...", "identity_level": 8 }

3. If your executor blocks loadstring, most advanced tools (code execution, hooks, closure analysis) will not work. Look for an executor with better UNC support

4. Some executors require manual enabling of certain functions in their settings

"No Roblox executor is connected" Error

This occurs when the MCP server is running but no Roblox executor has connected via WebSocket.

Solutions:

1. Ensure the server is running: rblx-mcp start

2. Verify the server is listening: curl http://localhost:28429/health

3. Inject the client script in your executor:

   loadstring(game:HttpGet("http://127.0.0.1:28429/mcp.lua"))()

4. Check the server console for registration messages

5. Verify firewall rules aren't blocking WebSocket connections on port 28429

6. If your executor doesn't support WebSocket, set transport to HTTP:

   getgenv().MCP_TRANSPORT = "http"

WebSocket Connection Issues

Executor won't connect:

1. Confirm the Roblox executor supports WebSocket.connect (check check_unc_capabilities)

2. Try HTTP fallback transport:

   getgenv().MCP_TRANSPORT = "http"

3. If using a remote server (not localhost), replace 127.0.0.1 with the server's IP:

   getgenv().MCP_HOST = "192.168.1.100"

4. Some executors block WebSocket to certain hosts. Try port 80 or 443 if your server supports it

Connection drops:

1. The server sends a heartbeat every 30 seconds

2. If you see frequent disconnects, check for network instability or anti-cheat interference

3. Use the HTTP transport fallback for more stable connections

Tool Returns "not handled by this executor"

This means the requested tool has no handler registered in the mcp.lua script.

Solutions:

1. Ensure you have the latest version: npm update -g roblox-mcp-difz

2. Re-inject mcp.lua (it's served fresh on every HTTP GET)

3. If the tool is very new, the public/mcp.lua may need to be regenerated

Environment Variables

Roblox-side (getgenv) Configuration

Set these before loading mcp.lua:

Programmatic API

import robloxMcp from 'roblox-mcp-difz';

// Create a configured server
const { app, server, tools, wss } = robloxMcp.createApp({ verbose: true });
server.listen(28429, () => {
  console.log(`Server ready (${tools.count} tools)`);
});

// Get tool definitions
const allTools = robloxMcp.getTools();
console.log(`Total tools: ${allTools.length}`);

Module exports

Security Notes

• The server listens on all interfaces (0.0.0.0) by default. If you only need local access, consider binding to 127.0.0.1 via your firewall or a reverse proxy.

• There is no authentication. Anyone who can reach the server port can invoke any tool. Do not expose the server to untrusted networks.

• Code execution tools (luau_code_executor, execute_custom_luau) provide full Lua VM access within the Roblox process, including the ability to call any API, hook any function, and modify any instance. Use with extreme caution.

• The server-side tools (get_roblox_processes, launch_roblox, open_game, capture_roblox_screenshot) execute on the Node.js host machine and can launch processes or enumerate running applications.

• Network interception tools (argument_spoofer, response_interceptor, remote_killswitch_toggler) can modify or block game network traffic, potentially violating terms of service.

• This tool is for educational and research purposes only. Unauthorized use against games you do not own or have explicit permission to test may violate Roblox Terms of Service.

License

MIT