Roblox Mcp Difz

Universal MCP (Model Context Protocol) server for Roblox game control, reverse engineering, network interception, input simulation, and game state manipulation.

Works with any MCP-compatible AI client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Cline/Continue.dev), or a custom MCP integration. 151 tools covering instance traversal, property inspection, remote event/function control, Lua code execution, function hooking, metatable manipulation, network traffic interception, file system operations, input simulation, and more.

---

Table of Contents

• Quick Start
• Installation
• Executor Setup
• MCP Client Configuration
• Commands
• UNC Capabilities Table
• Tool Listing by Category
• Architecture
• Multi-Instance Support
• Troubleshooting
• Environment Variables
• Programmatic API
• License

---

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"
    }
  }
}

Generic MCP Client

rblx-mcp setup --ai generic

This writes mcp-config.json to the current directory. Any MCP client that supports type: "http" transport can use:

http://localhost:28429/mcp

---

Commands

Command	Description
rblx-mcp / rblx-mcp --help	Show help
rblx-mcp start	Start HTTP + WebSocket server (port 28429)
rblx-mcp setup	Interactive setup wizard — configures AI platforms
rblx-mcp setup --ai <name>	Quick setup for a specific AI
rblx-mcp setup --ai-list	List supported AI platforms

Endpoints

Endpoint	Transport	Purpose
POST /	HTTP	MCP JSON-RPC 2.0
POST /mcp	HTTP	MCP JSON-RPC 2.0 (alias)
GET /mcp.lua	HTTP	Executor client script
GET /mcp.luau	HTTP	Executor client script (alias)
GET /type	HTTP	Server info JSON
GET /health	HTTP	Health check
WS /ws	WebSocket	Executor communication

---

UNC Capabilities Table

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.

UNC Function	Category	Dependent Tools	Fallback
getnilinstances	Instance Tree Traversal	nil_realm_scanner, get_nil_instances	Returns empty array
getconnections	Remote E&F	remote_connection_inspector, get_remote_connections	instance:GetConnections()
loadstring	Code Execution, Script Analysis, Closure Analysis, Function Hooking	luau_code_executor, execute_custom_luau, script_decompiler, closure_inspector, closure_upvalue_editor, function_interceptor_installer, function_hook_installer	None (core requirement)
gethiddenproperty	Hidden Properties	hidden_property_reader	Returns nil
sethiddenproperty	Hidden Properties	hidden_property_writer	No-op
setscriptable	Hidden Properties	property_scriptable_toggler	No-op
gethui	GUI Manipulation	gui_hierarchy_dumper, screen_text_extractor, notification_hider, clean_gui_traces, gui_button_clicker	Returns CoreGui
firesignal	GUI Manipulation, Instance Lifecycle	gui_button_clicker, signal_replicator	signal:Fire()
readfile	File System	file_reader	Returns empty string
writefile	File System	file_writer	No-op
delfile	File System	file_deleter	No-op
listfiles	File System	file_lister	No-op
isfile	File System	file_lister	Returns false
makefolder	File System	folder_creator	No-op
getcustomasset	File System	custom_asset_loader	Fails with error
getloadedmodules	Script & Module Analysis	get_loaded_modules, module_registry_scanner	Error reported
getrunningscripts	Script & Module Analysis	running_scripts_lister	Error reported
getscriptbytecode	Script & Module Analysis	script_source_ripper, script_decompiler, bytecode_disassembler	Error reported
getscriptclosure	Script & Module Analysis, Closure Analysis	script_closure_getter, closure_type_checker	Error reported
getscripthash	Script & Module Analysis	script_hash_calculator	Error reported
getcallingscript	Script & Module Analysis	calling_script_finder	Error reported
getsenv	Script & Module Analysis	script_environment_dumper	Error reported
getrenv	Script & Module Analysis	roblox_environment_viewer	Error reported
getthreadidentity	Script & Module Analysis	sandbox_analyzer	Returns 0
isexecutorclosure	Script & Module Analysis, Closure Analysis	sandbox_analyzer, closure_type_checker	Returns false
getgc	Script & Module Analysis, Registry & GC	gc_scanner, sandbox_analyzer	Error reported
getreg	Script & Module Analysis, Registry & GC	registry_scanner, registry_reader, sandbox_analyzer	Error reported
iscclosure	Closure Analysis	closure_type_checker	Error reported
islclosure	Closure Analysis	closure_type_checker	Error reported
getrawmetatable	Metatable Manipulation	metatable_seer, metatable_modifier, readonly_toggler	Falls to getmetatable
setrawmetatable	Metatable Manipulation	metatable_modifier, raw_metatable_setter	No-op
setreadonly	Metatable Manipulation	readonly_toggler	No-op
isreadonly	Metatable Manipulation	metatable_seer, readonly_toggler	Returns false
hookfunction	Function Hooking, Script Analysis, Network Traffic	function_interceptor_installer, function_hook_installer, spy_remote_traffic, traffic_interceptor_installer, remote_blocker_installer, argument_spoofer, response_interceptor	No-op
hookmetamethod	Function Hooking	namecall_spy	Error reported
getnamecallmethod	Function Hooking	namecall_spy	Returns empty string
fireclickdetector	Instance Lifecycle	fire_click_detector	No-op
fireproximityprompt	Instance Lifecycle	fire_proximity_prompt, interact_all_proximity_prompts	No-op
compareinstances	Instance Lifecycle	instance_comparer	Lua == operator
cloneref	Internal	All tools (service references)	Identity function
getpid	Internal	Multi-instance targeting	nil

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.

---

Tool Listing by Category

Game Metadata & Discovery (8 tools)

Tool	Description
get_game_metadata	PlaceId, UniverseId, JobId, player count, FPS, memory
game_metadata_collector	Extended metadata including creator info, server details, membership type
dump_workspace_players	Real-time data for every player: position, health, team, backpack, proximity prompts
local_player_state_dumper	Full local player state: account, character, GUI, backpack
get_local_player_data	LocalPlayer Backpack, Leaderstats, Character, Humanoid, ScreenGuis
get_workspace_objects	Recursive workspace dump: name, class, position, size, color, attributes
get_console_logs	LogService output filtered by type (error/warning/info) with timestamps
humanoid_state_extractor	Detailed Humanoid state: health, walkspeed, jumppower, state type, floor material
cursor_tracker	Read mouse cursor position, icon, and button state

Instance Tree Traversal (13 tools)

Tool	Description
recursive_tree_walker	Walk instance tree with depth, class, and name filters
service_discoverer	Enumerate all loaded DataModel services
child_watcher	Monitor a container for child additions/removals/reorderings
path_resolver	Resolve dot/slash-delimited paths to instance references
class_subtree_enumerator	Recursively enumerate all instances of a class and its subclasses
spatial_proximity_scanner	Find BaseParts within a radius around a world position
nil_realm_scanner	Find instances parented to nil (hidden/orphaned objects)
get_nil_instances	Enumerate every instance parented to nil outside the game tree
class_instance_collector	Collect all instances matching a class name within a scope
data_model_explorer	Top-down DataModel enumeration with depth control
datamodel_explorer	Alias for data_model_explorer
sibling_enumerator	Enumerate siblings of an instance within the same parent
get_instance_from_path	Resolve any game path string and return instance properties

Tags & Attributes (5 tools)

Tool	Description
tag_collector	Find instances by CollectionService tags (any/all mode)
tag_reader	Get all CollectionService tags on a specific instance
attribute_seeker	Search for instances with specific custom attributes
attribute_collector	Read named custom attributes from an instance
full_attribute_enumerator	Enumerate ALL custom attributes via GetAllAttributes()

Remote Events & Functions (8 tools)

Tool	Description
dump_remote_events	Scan services for all RemoteEvent/RemoteFunction instances
remote_surface_scanner	Same as dump_remote_events with search ancestor and class filtering
remote_event_trigger	Fire a RemoteEvent with typed arguments
remote_function_caller	Invoke a RemoteFunction and capture the server response
invoke_remote_function	Alias for remote_function_caller
fire_remote_event	Fire or invoke a remote with full argument support
remote_connection_inspector	Inspect all connected handlers on a remote
get_remote_connections	Alias for remote_connection_inspector

Code Execution (2 tools)

Tool	Description
luau_code_executor	Execute arbitrary Luau code with identity level control
execute_custom_luau	Execute Luau code in executor environment with full privileges

Property Access (9 tools)

Tool	Description
property_bulk_reader	Batch-read multiple properties from any instance
property_deep_dive	Deep inspection of a single property including type, security, and defaults
class_blueprint_viewer	Complete reflection metadata for any Roblox class
string_value_reader	Read and decode BinaryStringValue / UnicodeStringValue contents
security_metadata_analyzer	Analyze read/write/replication security on properties
property_mutator_generic	Set any writable property on any instance
property_value_seeker	Search tree for instances where a property has a specific value
value_container_scanner	Scan for ValueBase subclass children
object_value_resolver	Resolve ObjectValue references and typed value containers

Hidden Properties (3 tools)

Tool	Description
hidden_property_reader	Read non-scriptable properties via gethiddenproperty
hidden_property_writer	Write non-scriptable properties via sethiddenproperty
property_scriptable_toggler	Make a non-scriptable property read/write via setscriptable

GUI Manipulation (12 tools)

Tool	Description
gui_injector	Inject custom ScreenGui/BillboardGui/SurfaceGui into CoreGui/PlayerGui
inject_gui	Alias for gui_injector
screen_overlay_renderer	Render 2D drawing overlays (lines, circles, text, crosshairs)
viewport_capture_handler	Capture game viewport as base64 PNG/JPEG screenshot
gui_hierarchy_dumper	Recursively dump CoreGui tree with positions, sizes, visibility
screen_text_extractor	Extract rendered text from all visible GUI elements
element_geometry_reader	Read position, size, and visual properties of GUI elements
notification_hider	Detect, hide, and suppress in-game notifications and popups
clean_gui_traces	Hide/destroy/restore executor GUI elements from CoreGui/PlayerGui
gui_button_clicker	Fire click signals on GUI buttons programmatically
ui_element_clicker	Click on GUI elements by path with absolute positioning
ui_change_watcher	Monitor GUI for child additions, property changes, and removals

File System (6 tools)

Tool	Description
file_reader	Read files from executor filesystem via UNC readfile
file_writer	Write files to executor filesystem via UNC writefile
file_deleter	Delete files/folders via UNC delfile
file_lister	List files in a directory via UNC listfiles
folder_creator	Create folders via UNC makefolder
custom_asset_loader	Load custom assets via UNC getcustomasset

Player State (2 tools)

Tool	Description
modify_local_property	Modify character properties: WalkSpeed, JumpPower, Health, Noclip, InfiniteJump, Gravity
teleport_to_target	Instant CFrame teleportation to coordinates, player, instance, or mouse target

Input Simulation (11 tools)

Tool	Description
key_press_emitter	Simulate a single keyboard key press via VirtualInputManager
key_hold_controller	Hold a key down for a duration or release it
key_combo_simulator	Simulate chorded key combinations (Ctrl+C, Ctrl+Shift+Esc)
text_automated_typer	Type text character-by-character with configurable delays
mouse_move_absolute	Move cursor to absolute screen coordinates with smoothing
mouse_click_simulator	Simulate mouse button clicks at current or specified position
mouse_button_hold	Press and hold or release a mouse button
mouse_drag_emitter	Click-and-drag from start to end position with interpolation
scroll_wheel_simulator	Simulate mouse scroll wheel in vertical/horizontal directions
touch_input_simulator	Simulate touch gestures: tap, long-press, swipe, pinch
character_motion_controller	WASD-based character navigation to waypoints

Script & Module Analysis (13 tools)

Tool	Description
get_loaded_modules	List all loaded ModuleScripts in the registry
module_registry_scanner	Enumerate cached modules with dependency graphs and source inspection
running_scripts_lister	List all actively executing scripts
script_source_ripper	Extract source code from any script at runtime
bytecode_disassembler	Disassemble Luau bytecode from a loaded closure
runtime_bytecode_patcher	Patch bytecode instructions in a loaded function
script_decompiler	Decompile a script via LuaExpert/Medal/Konstant chain
script_closure_getter	Get the main closure of a script via getscriptclosure
script_hash_calculator	Compute script hash via getscripthash
calling_script_finder	Get the script that called the current context
script_environment_dumper	Dump a script's local environment (getsenv)
roblox_environment_viewer	Read and compare getrenv and getgenv globals
sandbox_analyzer	Analyze sandbox restrictions, identity level, and anti-tamper measures

Closure Analysis (5 tools)

Tool	Description
closure_type_checker	Check if a closure is C/Lua/executor with iscclosure/islclosure/isexecutorclosure
closure_inspector	Dump prototype tree, constants, upvalues, and debug info
closure_upvalue_editor	Read/modify upvalues on any loaded closure
dump_constants_and_upvalues	Inspect constants and upvalues of a function
debug_info_extractor	Extract comprehensive debug info: source, line numbers, upvalues, locals

Metatable Manipulation (4 tools)

Tool	Description
metatable_seer	Inspect metatables including hidden/locked ones
metatable_modifier	Set/replace/remove metamethods on any object
raw_metatable_setter	Set raw metatable bypassing __metatable protection
readonly_toggler	Toggle table readonly state via setreadonly/isreadonly

Function Hooking (4 tools)

Tool	Description
function_interceptor_installer	Install pre/post/replace hooks on global/instance functions
function_interceptor_remover	Remove a previously installed hook with safe restoration
function_hook_installer	Hook any Lua function using hookfunction
namecall_spy	Monitor namecall method invocations on a target object

Registry & GC Scanning (3 tools)

Tool	Description
registry_scanner	Scan the Lua registry table with key pattern and type filtering
registry_reader	Dump registry keyed by index
gc_scanner	Scan garbage collector for functions, tables, threads

Network Traffic Interception (9 tools)

Tool	Description
spy_remote_traffic	Hook FireServer/InvokeServer on all remotes and capture traffic
traffic_interceptor_installer	Install a global remote traffic interceptor with session management
traffic_interceptor_remover	Remove a traffic interceptor by session ID
remote_blocker_installer	Block specific remotes from sending to the server
remote_killswitch_toggler	Global killswitch for ALL outgoing remote traffic
argument_spoofer	Intercept and modify arguments before they reach the server
argument_type_analyzer	Probe a remote's expected argument types and handler signatures
traffic_filter_setter	Configure include/exclude filters for traffic interception
response_interceptor	Hook RemoteFunction return values and modify server responses

Network Ownership (3 tools)

Tool	Description
get_network_ownership	Analyze which parts are client-owned vs server-owned
network_ownership_mapper	Map network ownership across a container with filtering
replication_filter_checker	Analyze server ReplicationFilter for hidden objects/properties

Instance Lifecycle (8 tools)

Tool	Description
instance_factory	Create new instances of any Roblox class
instance_terminator	Destroy or remove instances from the hierarchy
instance_duplicator	Clone instances with position offset and renaming
instance_comparer	Compare two instances for reference equality
fire_click_detector	Fire a ClickDetector without physical clicking
fire_proximity_prompt	Fire a ProximityPrompt bypassing HoldDuration/range
interact_all_proximity_prompts	Trigger every ProximityPrompt in range
signal_replicator	Replicate a signal/event via replicatesignal

Camera & Viewport (3 tools)

Tool	Description
camera_state_reader	Read camera CFrame, Focus, FOV, CameraType, viewport
camera_controller	Lock/unlock/orbit/zoom camera with smooth transitions
world_to_screen_converter	Convert 3D world coordinates to 2D screen coordinates

Visual Overlays (2 tools)

Tool	Description
esp_label_manager	Create/update/destroy ESP text labels attached to players/NPCs/objects
billboard_attachment_manager	BillboardGui attachments floating above characters or parts

Lighting & Environment (7 tools)

Tool	Description
lighting_configurator	Modify Lighting: brightness, clock time, fog, ambient, shadows, technology
atmosphere_tweaker	Control Atmosphere density, glare, haze, color, decay
cloud_fog_controller	Control cloud settings, FogService, and depth fog
terrain_brush_controller	Fill/replace/read terrain voxels and materials
physics_engine_tuner	Modify workspace physics: gravity, collision, streaming
material_override_tool	Override part materials, physical properties, and MaterialVariants
sound_effect_manager	Play, stop, and control 3D sound effects

Character & Social (4 tools)

Tool	Description
character_appearance_modifier	Modify character appearance, body scale, skin tone, model swap
spawn_location_manager	Manage spawn locations, respawn behavior, and teleportation
chat_system_controller	Control chat: modify chat properties, send system messages, bypass filter
team_color_manager	Manage teams, team colors, player assignments, auto-assign

Utilities (3 tools)

Tool	Description
check_unc_capabilities	Test executor for all supported UNC functions and report support matrix
macro_recorder	Record mouse and keyboard input sequences into named macros
macro_replayer	Replay recorded macros with speed control and looping

Server-Side Tools (5 tools)

These tools execute on the Node.js server directly without requiring a Roblox executor.

Tool	Description
get_roblox_processes	List all running RobloxPlayerBeta processes on this machine
launch_roblox	Launch the Roblox client application
open_game	Open a Roblox game via roblox-player protocol
capture_roblox_screenshot	Take a screenshot of a Roblox window by PID
get_roblox_versions	List installed Roblox version directories

---

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        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   │               │                │
│  │(151 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)     │──│ (150+ 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 comprehensive compatibility layer that adapts to the executor's available UNC functions. Every function has a fallback strategy:

UNC Function	Fallback Behavior
WebSocket.connect	Falls back to HTTP polling transport
getnilinstances	Returns empty array
fireclickdetector	No-op
fireproximityprompt	No-op
firesignal	Uses signal:Fire() if available
getconnections	Uses instance:GetConnections()
gethiddenproperty	Returns nil
sethiddenproperty	No-op
setscriptable	No-op
hookfunction	No-op (tools that depend on it will report failure)
getrawmetatable	Falls to standard getmetatable
setrawmetatable	No-op
setreadonly	No-op
isreadonly	Returns false
gethui	Returns CoreGui
readfile	Returns empty string
writefile, delfile	No-op
isfile	Returns false
makefolder	No-op
getcustomasset	Fails with error
getloadedmodules, getrunningscripts, etc.	Fails with error
compareinstances	Uses Lua == operator

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

---

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

Variable	Default	Description
MCP_PORT	28429	HTTP server port

Roblox-side (getgenv) Configuration

Set these before loading mcp.lua:

Variable	Default	Description
getgenv().MCP_HOST	"127.0.0.1"	Server hostname/IP
getgenv().MCP_PORT	28429	Server port
getgenv().MCP_TRANSPORT	"auto"	Transport: "auto"
getgenv().MCP_WORKER_ID	auto-generated	Unique worker ID for multi-instance

---

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

Export	Type	Description
createApp(options?)	Function	Creates the Express app, HTTP server, WebSocket server, and all managers
getTools()	Function	Returns the full tool definitions array
McpHandler	Class	MCP JSON-RPC message handler
QueueManager	Class	Task queue for dispatching to executors
SessionManager	Class	Manages connected executor sessions
WsServer	Class	WebSocket server for executor communication
ToolDefinitions	Class	Tool registry

---

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