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.

Credit: This project is based on roblox-executor-mcp by notpoiu. Full credit to the original authors for the foundational work.

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.

Related MCP server: mcp-serotonin

Features

• Code Execution — Run Lua code and fetch data from the game client.

• Script Inspection — Decompile scripts and search across all sources (text/regex via script-grep, behavior via semantic-search-scripts).

• Instance Search — CSS-like selectors and hierarchy trees.

• GC Search — Scan the Luau garbage collector (getgc) for in-memory functions and tables that aren't reachable through the instance tree.

• Remote Spy — Intercept, log, block, and ignore Remotes/Bindables via Cobalt.

• GUI Interaction — Click buttons and type into text boxes.

• Screenshot — Capture Roblox window screenshots (Windows only).

• Multi-Client — Connect multiple Roblox clients at once.

• Primary / Secondary — Multiple MCP instances auto-coordinate with automatic promotion. Supports remote relaying via --baseurl. See Advanced.

• Local or hosted embeddings — Semantic search works with a local model (Ollama / LM Studio) or a hosted API. See Local model setup.

Tutorial

Prerequisites

• Node.js ≥ 18

• A Roblox executor that supports loadstring, request, and (preferably) WebSocket

Quick Start

1. Clone the server

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

2. Run the harness installer

The installer builds the server, lets you choose AI clients, writes supported MCP configs, and prints the Roblox loader script.

npm run install:harnesses

If your terminal has trouble with the interactive picker, use the plain numbered prompt:

npm run install:harnesses -- --plain

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

The update command can stop currently running MCP server processes, optionally pull latest changes, and always rebuilds the server.

Manual setup

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

For semantic search with a local embedding model (no API key), see the Local model setup.

3. Connect from Roblox

The installer prints this for you. Put it in 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

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. Port 16384 has no authentication. It binds to 127.0.0.1 (local machine only) by default; LAN exposure is opt-in via --allow-lan / --host. Never expose it to the internet. For cross-machine setups, use a local network, VPN, or SSH tunnel. See Advanced for details.

Credits

Based on roblox-executor-mcp by notpoiu — full credit to the original project for the foundation this builds on. Remote spy is powered by Cobalt.

License

MIT — the original copyright and license notice are preserved.