<p align="center"> <img src="docs/banner-new.svg" alt="Roblox Executor MCP" width="900"/> </p>

Roblox Executor MCP Server

An MCP server that allows Agents to interact with a running Roblox game client — execute code, inspect scripts, spy on remotes, and more.

Contributors

• amyyzing
• Claude Mythos 5
• ChatGPT

Dashboard

Roblox Executor MCP includes a local web dashboard at:

http://localhost:16384/

Use it to see connected Roblox clients, inspect scripts, run tools, view server logs, configure semantic search, and index games for semantic script search.

Features

• Code Execution — Run Lua code and fetch data from the game client.
• Script Inspection — Decompile scripts and search across all sources.
• Controlled Script Indexing — Start, stop, inspect, or fully resync source mapping on demand; expensive initial indexing is opt-in.
• Instance Search — CSS-like selectors and hierarchy trees.
• Runtime Diagnostics — Inspect transport latency, executor capabilities, decompiler health, and live mapping state.
• Bounded Runtime Search & Events — First-match GC searches plus bounded waits; console and non-selector instance journals support resumable cursors.
• Remote Spy — Inspect, block, and filter Remotes/Bindables from a reviewed Cobalt build that you preload yourself; the connector never downloads spy code.
• Unified Input — Keyboard, text, mouse, scroll, prompt, click-detector, and touch interaction.
• Screenshot — Capture Roblox window screenshots (Windows only).
• Multi-Client — Connect multiple Roblox clients at once.

Prerequisites

• Node.js ≥ 18
• Bun ≥ 1.3 for the interactive OpenTUI harness installer
• A Roblox executor that supports loadstring, request, and (preferably) WebSocket

Quick Start

1. Clone the server

git clone https://github.com/amyyzing/ai-mcp.git
cd ai-mcp

2. Run the installer

The installer opens a guided browser setup. It builds the server, configures selected AI harnesses, optionally installs the packaged Roblox MCP skill and Roblox connector, and can register the shared server to run in the background with your computer.

On Windows, double-click setup.cmd. It checks for Node.js 18+, installs Node.js LTS through WinGet when necessary, and then opens the guided installer.

For manual or non-Windows setup, run:

npm run install:harnesses

The browser opens with a one-time secure installer link. Keep the terminal open until setup finishes. The normal server build consumes the committed connector.luau artifact, so installs do not require Darklua. Connector developers can install the pinned tool with rokit install, edit connector-src/, and regenerate the artifact with npm run build:connector.

For a terminal-only setup, use the explicit CLI installer. The CLI picker is built with OpenTUI and runs through Bun:

npm run install:harnesses:cli

If the interactive terminal picker is unavailable, add -- --plain. Press s in the picker or pass -- --show-all-harnesses to reveal every supported config target. After writing configs, both installers can automatically restart supported GUI harnesses that are currently running. CLI-only harness sessions still receive a restart instruction when they cannot be relaunched safely.

To explore the browser flow without changing configs, installing packages, registering a service, or restarting harnesses, run:

npm run install:harnesses:preview

Pass -- --no-open to either browser command to start it without opening a browser. Pass -- --host 0.0.0.0 to access it from another device over your LAN or Tailscale; use the complete tokenized URL printed by the installer.

The installer can also place the Roblox loader into a detected executor autoexec folder, such as MacSploit on macOS or supported Windows executor autoexec folders. Use the prompt, or run:

npm run getscript -- --autoexec

It can also help with:

• cross-machine setup on the same LAN
• copying the Roblox loader to your clipboard
• optional Ollama embeddinggemma setup for semantic indexing
• pulling latest repo changes before install/build

To update an existing install later, run:

npm run update

You can also open Dashboard → Settings → Server updates and select Update now.

Manual setup

If you prefer to configure a client yourself, use the setup guide for your client:

Client	Guide
Cursor	Setup Guide
Claude Desktop	Setup Guide
Claude Code	Setup Guide
Codex CLI	Setup Guide
Windsurf	Setup Guide
Antigravity	Setup Guide
BLACKBOX AI	Setup Guide
ZCode	Setup Guide

3. Connect from Roblox

The installer prints this for you. Put it in your executor or Auto Execute:

while not getgenv().MCP_Loaded do
    local bridgeUrl = getgenv().BridgeURL or "localhost:16384"
    local bridgeBase = string.match(bridgeUrl, "^https?://") and bridgeUrl or ("http://" .. bridgeUrl)
    pcall(function() loadstring(game:HttpGet(bridgeBase .. "/script.luau"))() end)

    task.wait(0.15)
end

Optional settings (set before the loadstring):

getgenv().BridgeURL = "10.0.0.4:16384"                  -- host:port, or https://bridge.example
getgenv().MCPAuthToken = "replace-with-your-pairing-token" -- required for remote bridges
getgenv().DisableWebSocket = true                        -- optional: force HTTP polling
getgenv().EnableInitialScriptDecompMapping = true        -- opt into full indexing on connect
getgenv().MCP_FailedScriptResyncInterval = 30            -- retry failed script syncs periodically
getgenv().MCP_FailedScriptResyncBatchSize = 8            -- bound each periodic retry batch

Full-game script indexing is off by default to keep large experiences responsive. Use the script-index-start MCP tool when needed, or set EnableInitialScriptDecompMapping = true before loading the connector.

Transport selection is automatic. The connector detects common executor WebSocket APIs, attempts a real connection, and falls back to HTTP polling if WebSocket is missing or broken. DisableWebSocket is only a troubleshooting override; normal users do not need to set it.

When loading the connector from another machine, authenticate the initial download too:

local HttpService = game:GetService("HttpService")
local bridgeUrl = getgenv().BridgeURL
local token = getgenv().MCPAuthToken
local bridgeBase = string.match(bridgeUrl, "^https?://") and bridgeUrl or ("http://" .. bridgeUrl)
loadstring(game:HttpGet(
    bridgeBase .. "/script.luau?token=" .. HttpService:UrlEncode(token)
))()

After the MCP server starts and Roblox connects, open the dashboard:

http://localhost:16384/

Community

Have a suggestion or need help? Join the Discord server.

Security

This server allows arbitrary code execution. Only use with AI clients you trust. The bridge binds to loopback by default. Remote mode requires an explicit bind host and pairing token; even with authentication, never expose it directly to the internet. Plain http:///ws:// LAN traffic is not encrypted, so its token, game data, source, and commands are visible and modifiable by anyone able to intercept that network. Prefer a VPN/SSH tunnel or an https:// TLS-terminating bridge. See Advanced for details.

License

MIT