Roblox Executor MCP

🚀 Roblox Executor MCP Server

An MCP server that bridges LLMs and a running Roblox Game Client, enabling code execution, script inspection, remote spying, and more.

✨ Features

• Code Execution & Data Querying: Run Lua and fetch data from the game client.
• Script Inspection: Decompile LocalScripts/ModuleScripts and search across sources.
• Instance Search: Use CSS-like selectors via QueryDescendants and hierarchy trees.
• Remote Spy: Integrate with Cobalt to intercept, log, block, and ignore Remotes/Bindables.
• Multi-Client: Connect multiple Roblox clients simultaneously and target each by clientId. Access the dashboard at http://localhost:16384/.
• Screenshot: Capture Roblox window screenshots (Windows only). When running as a secondary, screenshots are relayed to the primary host.
• Primary / Secondary: Multiple MCP instances auto - coordinate. Secondaries relay through the primary with automatic promotion. Supports remote primaries via --baseurl.

📦 Installation

Prerequisites

• A Roblox executor supporting loadstring, request, and (preferably) WebSocket.
• Node.js ≥ 18.

Installation Steps

pnpm install && pnpm run build

🚀 Quick Start

Add to your AI Client

• Cursor: Go to Settings > Features > MCP > Add. Set name as roblox - executor - mcp, type as command, and command as node /path/to/MCPServer/dist/index.js.
• Claude Desktop / Antigravity: Add the following to your JSON config:

{
  "mcpServers": {
    "roblox-executor-mcp": {
      "command": "node",
      "args": ["/path/to/MCPServer/dist/index.js"]
    }
  }
}

• Codex: Go to Settings > MCP Settings > Add server. Set name as roblox - executor - mcp, type as STDIO, command as node, and args as /path/to/MCPServer/dist/index.js.

Connect from Roblox

Run connector.luau in your executor, or use the quick loader:

-- getgenv().BridgeURL = "10.0.0.4:16384" (defaults to localhost, change if needed)
-- getgenv().DisableWebSocket = true
-- getgenv().DisableInitialScriptDecompMapping = true (disables script decompilation untill you run a script related tool)
loadstring(game:HttpGet("https://raw.githubusercontent.com/notpoiu/roblox-executor-mcp/refs/heads/main/connector.luau"))()

💻 Usage Examples

Tools

🔧 Technical Details

Primary / Secondary Mode

By default, the server starts as a primary on port 16384. If that port is already taken, it automatically becomes a secondary that relays all tool calls through the primary. When the primary disconnects, a secondary promotes itself.

Remote primary (--baseurl)

Connect this instance as a secondary to a remote primary. This is useful when your AI client is on macOS/Linux but Roblox is on a Windows machine:

{
  "mcpServers": {
    "roblox-executor-mcp": {
      "command": "node",
      "args": [
        "/path/to/MCPServer/dist/index.js",
        "--baseurl",
        "http://<primary-host>:16384"
      ]
    }
  }
}

⚠️ Important Note

screenshot - window and list - roblox - windows are forwarded over HTTP to the primary, so a Mac secondary can capture windows running on a Windows primary.

📄 License

Security Note

• Arbitrary code execution: Only use with trusted LLMs. Any connected AI client can run code in your Roblox session.
• Do not expose the HTTP server to the internet. Port 16384 is unauthenticated. Anyone who can reach it can execute code in your game, take screenshots of your screen, and read client data. If you need cross - machine access (e.g., --baseurl), use a local network / VPN or an SSH tunnel — never forward the port through a public router or cloud firewall.