Which integrations are available for this server?

Provides tools for controlling, reversing, and exploiting Roblox games, including instance tree exploration, property inspection, visual tracking, input simulation, environment manipulation, memory hooking, network traffic, and state bypass.

How do I use roblox-mcp-difz?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@roblox-mcp-difz list all instances in the Roblox game" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

roblox-mcp-difz

by Difz25x

Overview Schema Related Servers Score Discussions

TypeScript

Local

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.

Related MCP server: Roblox Studio Ultimate MCP Server

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

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

AI Client sends MCP JSON-RPC (tool call) via HTTP POST to /mcp
MCP Handler validates the tool name and dispatches it
Server-side tools (process management, screenshots) execute directly in Node.js
Executor tools are queued in the Queue Manager and sent via WebSocket to all connected Roblox executors
mcp.lua receives the task, routes it to the correct handler, which interacts with the Roblox DataModel using UNC functions
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:

LuaExpert (api.lua.expert) — primary
Medal (medal.upio.dev) — fallback 1
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:

Run check_unc_capabilities to identify which functions are blocked

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

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

If your executor blocks loadstring, most advanced tools (code execution, hooks, closure analysis) will not work. Look for an executor with better UNC support
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:

Ensure the server is running: rblx-mcp start
Verify the server is listening: curl http://localhost:28429/health

Inject the client script in your executor:

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

Check the server console for registration messages
Verify firewall rules aren't blocking WebSocket connections on port 28429
If your executor doesn't support WebSocket, set transport to HTTP:
```
getgenv().MCP_TRANSPORT = "http"
```

WebSocket Connection Issues

Executor won't connect:

Confirm the Roblox executor supports WebSocket.connect (check check_unc_capabilities)
Try HTTP fallback transport:
```
getgenv().MCP_TRANSPORT = "http"
```
If using a remote server (not localhost), replace 127.0.0.1 with the server's IP:
```
getgenv().MCP_HOST = "192.168.1.100"
```
Some executors block WebSocket to certain hosts. Try port 80 or 443 if your server supports it

Connection drops:

The server sends a heartbeat every 30 seconds
If you see frequent disconnects, check for network instability or anti-cheat interference
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:

Ensure you have the latest version: npm update -g roblox-mcp-difz
Re-inject mcp.lua (it's served fresh on every HTTP GET)
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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

1dRelease cycle

12Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Difz25x/roblox-mcp-difz'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

roblox-mcp-difz

Table of Contents

Quick Start

Installation

Global install (recommended)

Run without installing

Install from source

Requirements

Executor Setup

1. Start the server

2. Inject the client script

3. Verify connection

getgenv() Configuration

MCP Client Configuration

Claude Code

Claude Desktop

Cursor

Windsurf

VS Code (Cline / Continue.dev)

Generic MCP Client

Commands

Endpoints

UNC Capabilities Table

Tool Listing by Category

Game Metadata & Discovery (8 tools)

Instance Tree Traversal (13 tools)

Tags & Attributes (5 tools)

Remote Events & Functions (8 tools)

Code Execution (2 tools)

Property Access (9 tools)

Hidden Properties (3 tools)

GUI Manipulation (12 tools)

File System (6 tools)

Player State (2 tools)

Input Simulation (11 tools)

Script & Module Analysis (13 tools)

Closure Analysis (5 tools)

Metatable Manipulation (4 tools)

Function Hooking (4 tools)

Registry & GC Scanning (3 tools)

Network Traffic Interception (9 tools)

Network Ownership (3 tools)

Instance Lifecycle (8 tools)

Camera & Viewport (3 tools)

Visual Overlays (2 tools)

Lighting & Environment (7 tools)

Character & Social (4 tools)

Utilities (3 tools)

Server-Side Tools (5 tools)

Architecture

Data Flow

Communication Protocol

Multi-Instance Support

UNC Compatibility Layer

Decompilation Chain

Troubleshooting

Check UNC Capabilities

"Attempt to call blacklisted function" Error

"No Roblox executor is connected" Error

WebSocket Connection Issues

Tool Returns "not handled by this executor"

Environment Variables

Roblox-side (getgenv) Configuration

Programmatic API

Module exports

Security Notes

License

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API