roblox-mcp-difz

Universal MCP server for Roblox game control, reverse engineering, and exploitation.

151 tools across 12 categories — Instance Tree Exploration, Property Inspection, Visual Tracking, Input Simulation, Environment Manipulation, Memory Hooking, Network Traffic, Closure Hooking, Environment Exploration, Filesystem Operations, Script Introspection, Metatable Manipulation.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Cline/Continue), and any MCP-compatible AI.

Install

npm install -g roblox-mcp-difz

Or run directly:

npx roblox-mcp-difz

Usage

# Start HTTP + WebSocket server (default port 28429)
roblox-mcp-difz

# Start stdio MCP transport (for AI integration)
roblox-mcp-difz start:stdio

# Interactive setup wizard — configure your AI
roblox-mcp-difz setup

# Quick setup for a specific AI
roblox-mcp-difz setup --ai claude-code
roblox-mcp-difz setup --ai claude-desktop
roblox-mcp-difz setup --ai cursor

Setup Wizard

$ roblox-mcp-difz setup

  Select AI platform(s) to configure:

    1. 🤖 Claude Code
    2. 💻 Claude Desktop
    3. 🔷 Cursor
    4. 🏄 Windsurf
    5. 📝 VS Code (Cline / Continue)
    6. 🔌 Generic MCP Client

  Enter numbers (comma-separated, e.g. "1,3" or "all"):

The wizard auto-detects config paths, creates the files, and merges with existing configs.

Roblox Executor Setup

Inject http://localhost:28429/mcp.luau into your Roblox executor.

The client supports WebSocket transport by default with HTTP polling fallback. It uses UNC (Universal Compatibility) functions with graceful fallbacks for maximum executor compatibility.

getgenv() Configuration

Set these before loading mcp.luau to override defaults:

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

Features

151 MCP Tools

Category	Count	Description
Instance Tree Exploration	17	Walk/search/filter the Roblox DataModel
Property Inspection	15	Read properties, attributes, tags, metadata
Visual & Screen Tracking	17	GUI hierarchy, camera, world-to-screen, click GUI
Input & Macro Simulation	14	Mouse/keyboard simulation, key combos, text typing
Environment Manipulation	16	Modify Lighting, Terrain, Sounds, Physics, etc.
Network Traffic	22	Remote scanning, firing, spying, blocking
Memory & Function Hooking	19	Decompile, hook, metatable, closure inspection
Closure & Function Ops	2	hookfunction, closure type checking
Environment Exploration	4	getgc, getreg, getrenv, getsenv
Filesystem Operations	6	read/write/list/delete files, assets
Script Introspection	4	Running scripts, call stack, closures, hashes
Metatable Manipulation	3	Raw metatables, readonly, namecall spy
Server-Side Tools	5	Process listing, launch Roblox, open game, screenshot

Multi-Instance Support

Each executor registers with a unique worker_id. Tasks can target specific Roblox instances by PID:

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

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

UNC Compatibility Layer

All UNC functions have fallbacks if the executor doesn't support them:

Function	Fallback
WebSocket.connect	HTTP polling
firesignal	signal:Fire()
getconnections	instance:GetConnections()
getscriptbytecode	Error (tools restricted)
decompile	LuaExpert → Medal → Konstant chain
request	Injected via loadstring
getgenv()	_G

Decompilation Chain

Automatic fallback through 3 decompile services:

1. LuaExpert (api.lua.expert) — primary
2. Medal (medal.upio.dev) — fallback 1
3. Konstant (api.plusgiant5.com) — fallback 2

Architecture

┌─────────────┐     JSON-RPC 2.0     ┌──────────────┐     WebSocket/HTTP    ┌──────────┐
│  AI (Claude) │ ──────────────────→  │  Node Server  │ ──────────────────→  │ Roblox    │
│  Cursor      │  POST / or /mcp     │  :28429       │  ws://host/ws        │ Executor  │
│  etc.        │ ←──────────────────  │  + stdio MCP  │ ←──────────────────  │ (mcp.luau)│
└─────────────┘                      └──────────────┘                      └──────────┘

Commands

Command	Description
roblox-mcp-difz	Start HTTP + WebSocket server
roblox-mcp-difz start	Same as above
roblox-mcp-difz start:stdio	Start stdio MCP transport + HTTP/WS
roblox-mcp-difz setup	Interactive setup wizard
roblox-mcp-difz setup --ai <name>	Setup for a specific AI
roblox-mcp-difz --help	Show help

API (programmatic)

import robloxMcp from 'roblox-mcp-difz';

// Create a configured server
const { app, server, tools } = robloxMcp.createApp({ verbose: true });
server.listen(28429);

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

Environment

Variable	Default	Description
MCP_PORT	28429	HTTP server port

License

MIT