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

Roblox Executor MCP + Vyre Dashboard

An MCP server that lets AI agents drive a running Roblox client — execute Luau, decompile and search scripts, spy on remotes, walk the datamodel, automate the UI, and more — with Vyre, a modern local web dashboard on top.

The upstream project went offline, so this is a maintained, installable distribution. Same engine, a fully redesigned dashboard, and new tools. MIT-licensed (see LICENSE).

Vyre dashboard

Served locally at http://localhost:16384/ once the server is running.

<table> <tr> <td><img src="docs/dashboard/server.png" alt="Server topology"/></td> <td><img src="docs/dashboard/scripts.png" alt="Scripts Explorer"/></td> </tr> <tr> <td align="center"><b>Live relay topology</b></td> <td align="center"><b>Studio-style script Explorer</b></td> </tr> </table>

<details> <summary>More views — Tools, Logs, Settings</summary>

</details>

Dashboard highlights

• Floating dock navigation + ⌘K command palette with grouped, highlighted results.
• Mission-control overview — hero client card, uptime ring, live stat tiles, quick actions, activity ticker.
• Live relay topology — animated MCP-core network graph with flowing packets and clickable client nodes.
• Studio-style Scripts Explorer — services → folders → scripts tree with a syntax-highlighted source viewer, plus the classic Scripts Synced / Semantic Index progress panels.
• Grouped logs — Activity vs System, level filters, search, and duplicate collapsing.
• Embedding settings — OpenAI / Ollama, save / test / clear, and a "Suggest for my machine" button that reads your GPU and recommends a local model.
• Six color themes, real player headshots, latency chip, snapshot export, and a demo mode.

MCP features

• Code execution — run Luau and fetch data from the game client.
• Script inspection — decompile scripts, script-grep, and semantic (meaning-based) search.
• Instance search — CSS-like selectors and descendant trees.
• Remote spy — intercept, log, block, and ignore Remotes/Bindables (via Cobalt).
• UI + input automation — click by text, fire ClickDetectors/ProximityPrompts, type, move the camera, path the character.
• Screenshots — capture the Roblox window (Windows only).
• Multi-client — connect several Roblox clients; primary/secondary instances auto-coordinate and can relay over a LAN with --baseurl.
• ~150 convenience tools on top of the raw channel, plus the new intel tools below.

New tools

Tool	What it returns
get-avatar-appearance	A player's HumanoidDescription — body colors, scales, clothing, worn accessories
count-instances-by-class	Descendants grouped by ClassName under a root, largest-first
list-nearby-players	Other players sorted by distance, with health and team
list-playing-sounds	Currently playing Sounds with volume, live loudness, and path
list-playing-animations	Animation tracks playing on a player, with id, weight, speed, loop
raycast-forward	First instance hit by a ray from the camera — name, class, distance, material

Prerequisites

• Node.js ≥ 18
• Bun ≥ 1.3 for the interactive harness installer (auto-installed if missing)
• A Roblox executor with loadstring, request, and preferably WebSocket

Quick start

1. Clone

git clone https://github.com/dedankschool-oss/roblox-executor-mcp.git
cd roblox-executor-mcp

2. Install into your AI client

The harness installer builds the server, lets you pick AI clients, writes their MCP configs, and prints the Roblox loader.

npm run install:harnesses

Trouble with the interactive picker? Use the plain prompt:

npm run install:harnesses -- --plain

It can also drop the loader into a detected executor autoexec folder:

npm run getscript -- --autoexec

Update an existing install later (stops running server processes, optionally pulls, always rebuilds):

npm run update

Manual setup

Prefer to wire a client yourself? See the guide for your client:

Client	Guide
Cursor	Setup
Claude Desktop	Setup
Claude Code	Setup
Codex CLI	Setup
Windsurf	Setup
Antigravity	Setup

Or run it directly:

npm run build
npm start

3. Connect from Roblox

Paste this into your executor (or Auto Execute):

local bridgeUrl = getgenv().BridgeURL or "localhost:16384"
loadstring(game:HttpGet("http://" .. bridgeUrl .. "/script.luau"))()

Optional settings (set before the loadstring):

getgenv().BridgeURL = "10.0.0.4:16384"               -- default: localhost:16384
getgenv().DisableWebSocket = true                     -- force HTTP polling
getgenv().DisableInitialScriptDecompMapping = true    -- skip initial decompilation

Then open the dashboard at http://localhost:16384/.

Semantic search & embeddings

Semantic search turns decompiled scripts into vectors so you can search by meaning ("how does data saving work") instead of exact text. Pick a provider in Settings → Embedding Provider:

• OpenAI (text-embedding-3-small) — cloud, needs an API key, no local compute.
• Ollama — runs locally on your GPU, free and private.

For a decent GPU, local Ollama is great. Recommended models:

Model	Notes
mxbai-embed-large	Highest quality; ideal if you have a dedicated GPU
nomic-embed-text	Fast, excellent for code; light on VRAM
embeddinggemma	Newer Google model; solid all-rounder

ollama pull mxbai-embed-large

The dashboard's "Suggest for my machine" button detects your GPU and picks a model for you.

Security

This server allows arbitrary code execution. Only use it with AI clients you trust. Port 16384 has no authentication — never expose it to the internet. For cross-machine setups use a LAN, VPN, or SSH tunnel. See Advanced.

License

MIT. The original engine is MIT-licensed; that notice is retained in LICENSE.