roblox-mcp-difz

The Universal Model Context Protocol (MCP) server for Roblox game control, reverse engineering, and multi-session automation.

Works out-of-the-box with Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Cline/Continue), or any MCP-compliant AI client. Packed with 80 streamlined tools (and full backward-compatible legacy aliases), non-blocking remote interception, cross-game teleport persistence, and multi-instance orchestration.

Quick Start (30 Seconds)

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

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

# 3. Start the MCP server
rblx-mcp start

# 4. Inject loader into your Roblox executor (Real, Solara, Wave, Delta, etc.)
loadstring(game:HttpGet("http://127.0.0.1:28429/mcp.lua"))()

Open the Command Deck Dashboard in your browser at http://localhost:28429 to monitor active clients, run interactive tool tests, and view live telemetry.

Related MCP server: Roblox Executor MCP

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│                   AI Client (Claude / Cursor)                    │
│             Calls any tool with optional worker_id/pid           │
└──────────────────────────────┬───────────────────────────────────┘
                               │ MCP JSON-RPC 2.0 (HTTP / Stdio)
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                   roblox-mcp-difz Server (:28429)                │
│                                                                  │
│  ┌─────────────────────────┐     ┌────────────────────────────┐  │
│  │ Multi-Session Router    │     │ Server Management APIs     │  │
│  │ Target PID/Worker or    │     │ /api/tools, /api/sessions  │  │
│  │ Broadcast to ALL window │     │ /api/processes, /health    │  │
│  └───────────┬─────────────┘     └────────────────────────────┘  │
│              │                                                   │
│              ├──────────────────────┐                            │
│              ▼                      ▼                            │
│     ┌─────────────────┐    ┌──────────────────┐                  │
│     │ WebSocket (/ws) │    │ HTTP Stream      │                  │
│     │ Realtime Push   │    │ Long-Poll Fallback│                 │
│     └────────┬────────┘    └────────┬─────────┘                  │
└──────────────┼──────────────────────┼────────────────────────────┘
               │                      │
               ▼                      ▼
┌──────────────────────────────────────────────────────────────────┐
│                 Roblox Game Clients (public/mcp.lua)             │
│  • Non-blocking __namecall hook with setnamecallmethod           │
│  • Teleport autoexecute via queue_on_teleport                    │
│  • Dual-transport worker (WebSocket + Stream)                    │
│  • 111 tools: DataModel, Remotes, GUI, Input, Memory, Filesystem │
└──────────────────────────────────────────────────────────────────┘

Key Capabilities

1. Non-Blocking Remote Interception (spy-remotes)

• Transparent network pass-through: __namecall restores setnamecallmethod(method) before forwarding to engine C handlers.

• Zero frame drops: Argument cloning and serialization execute asynchronously in background tasks.

• Clean varargs & return handling: RemoteFunction:InvokeServer returns the exact server response back to the game thread without freezing.

2. Cross-Game Teleport Autoexecute (set-autoexecute)

• Automatically re-injects mcp.lua across world hops, matchmaking, and dimensions using queue_on_teleport.

• Hooks Players.LocalPlayer.OnTeleport and automatically re-arms in the new place.

• Toggle anytime via AI tool call (set-autoexecute) or web dashboard switch.

3. Universal Multi-Session Orchestration

Run as many simultaneous Roblox instances as you want (multi-account farming, alt control, multi-boxing).

• Target specific instance: Pass worker_id (or pid, session_id) to any tool:

  { "name": "execute-script", "arguments": { "pid": 11360, "code": "print('hello from PID 11360')" } }

• Automatic Multi-Session Fanout: Omit target arguments to execute the tool across all connected instances concurrently. Results are returned in a table per session:

  {
    "multi_session": true,
    "total_sessions": 2,
    "results": {
      "PlayerOne_11360": { "success": true, "pid": 11360, "result": { "health": 100 } },
      "PlayerTwo_14200": { "success": true, "pid": 14200, "result": { "health": 85 } }
    }
  }

4. Dual Transport (WebSocket & Stream)

Two interchangeable transport engines carry identical task/result JSON:

• WebSocket (ws://localhost:28429/ws): Bidirectional low-latency connection for executors supporting UNC WebSocket.connect.

• Stream (http://localhost:28429/stream/*): HTTP long-polling fallback for executors with non-standard sockets (e.g. Real __on_message_bind).

• Auto-fallback: In auto mode, clients attempt WebSocket and automatically switch to Stream if the connection fails.

Tools Overview (80 Streamlined Tools)

Every tool accepts an optional workerId as its first parameter (if omitted, executes across all connected game instances). Legacy aliases are retained so all existing scripts continue functioning. Below is a categorized index:

Command Line Reference

# Start server in foreground with interactive menu
rblx-mcp start

# Run server as hidden background daemon with system tray icon
rblx-mcp daemon

# Run in Stdio mode (for CLI MCP clients like Claude Code without HTTP)
rblx-mcp stdio

# Run setup wizard for AI platform configuration
rblx-mcp setup

# Stop running background server
rblx-mcp stop

# Check for latest updates
rblx-mcp update

Environment Variables

• MCP_PORT: HTTP/WebSocket server port (default: 28429).

• MCP_TRANSPORT: Initial transport mode (auto, ws, stream). Default: auto.

• MCP_HOST: Custom bind address (default: 127.0.0.1).

Server Management Endpoints

License

MIT © Difz25x