Skip to main content
Glama
Roblox Executor MCP

Roblox Executor MCP

by xixfaces

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.

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: Roblox MCP Server

Features

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

  • Script Inspection — Decompile scripts and search across all sources.

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

  • 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.

Tutorial

roblox-executor-mcp installation guide

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:

Client

Guide

Cursor

Setup Guide

Claude Desktop

Setup Guide

Claude Code

Setup Guide

Codex CLI

Setup Guide

Windsurf

Setup Guide

Antigravity

Setup Guide

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 — never expose it to the internet. For cross-machine setups, use a local network, VPN, or SSH tunnel. See Advanced for details.

License

MIT

Available Tools

21 tools
block-remoteBlock or unblock a remoteA

Block or unblock a Roblox remote by exact name and direction. Requires ensure-remote-spy first; use get-remote-spy-logs to discover candidates.

Inputs: remoteName (required), direction (required), shouldBlock.

clear-remote-spy-logsClear all remote spy logsA

Clear all captured Cobalt remote spy logs. Requires ensure-remote-spy first.

Inputs: no named parameters.

click-buttonClick a GuiButtonA

Click a Roblox TextButton or ImageButton by firing its GUI signals. Use when direct UI activation is needed inside the active client.

Inputs: path (required), action.

ensure-remote-spyEnsure the Cobalt remote spy is loadedA

Load or verify the Cobalt remote spy in the active Roblox client. Call before reading, clearing, blocking, or ignoring remote spy logs.

Inputs: no named parameters.

executeExecute Code in the Roblox Game ClientA

Execute Luau in the active Roblox client without returning output. Use get-data-by-code instead when you need returned values.

Inputs: code (required), threadContext.

execute-fileExecute a Luau file in the Roblox Game ClientA

Execute a local .luau or .lua file in the active Roblox client without returning output. Use get-data-by-code instead when you need returned values.

Inputs: filePath (required), threadContext.

get-console-outputGet the roblox developer console output from the Roblox Game ClientC

Read recent Roblox developer console logs from the active client. Use limit and logsOrder to control volume and ordering.

Inputs: limit, logsOrder, filter.

get-data-by-codeGet data by codeB

Execute Luau in the active Roblox client and return serialized raw Lua values. The code must return values; do not manually JSON-encode them.

Inputs: code (required), threadContext, timeout.

get-descendants-treeGet the descendants tree of a Roblox instanceA

Get a depth-limited hierarchy of descendants under a Roblox instance. Use for broad structure exploration; use search-instances for selector-based filtering.

Inputs: root (required), maxDepth, classFilter, maxChildren.

get-game-infoGet information about the current Roblox gameA

Get current Roblox place and universe metadata such as PlaceId, GameId, and PlaceVersion.

Inputs: no named parameters.

get-remote-spy-logsGet captured remote spy logs from CobaltA

List captured Cobalt remote and bindable call logs. Requires ensure-remote-spy first; supports direction and name filters to narrow noisy logs.

Inputs: direction, remoteNameFilter, limit, maxCallsPerRemote.

get-script-contentGet the content of a script in the Roblox Game ClientA

Get decompiled source for a Roblox script by path, script proxy, or getter code. Use startLine/endLine for a focused range when the full script is large.

Inputs: scriptGetterSource, scriptPath, startLine, endLine.

ignore-remoteIgnore or unignore a remoteA

Ignore or unignore logging for a Roblox remote by exact name and direction. Requires ensure-remote-spy first; ignored remotes still fire.

Inputs: remoteName (required), direction (required), shouldIgnore.

list-clientsList connected Roblox clientsA

List connected Roblox game clients with clientId and session metadata. Use before set-active-client when multiple clients are connected or the target client is unknown.

Inputs: no named parameters.

list-roblox-windowsList visible Roblox windowsA

List visible Roblox OS windows with PIDs. Use before screenshot-window when multiple Roblox windows may be open.

Inputs: no named parameters.

screenshot-windowTake a screenshot of a Roblox windowA

Capture an actual OS screenshot of a Roblox window via Windows APIs. Provide pid when multiple windows are open; secondary servers relay capture to the primary host.

Inputs: pid.

script-grepGrep across all scripts in the gameA

Search decompiled Roblox scripts with JavaScript regex or literal string matching. Use for exact identifiers or code patterns; use semantic-search-scripts when behavior is known but names are not.

Inputs: query (required), limit, contextLines, maxMatchesPerScript, +3 more.

search-instancesSearch for instances in the gameB

Search Roblox instances with QueryDescendants selector syntax. Use for class, name, tag, property, and attribute queries against a chosen root.

Inputs: selector (required), root, limit.

semantic-search-scriptsSemantically search scripts in the gameA

Find decompiled Roblox scripts by behavior using semantic embeddings. Use when exact identifiers are unknown; use script-grep for exact text or regex.

Inputs: query (required), limit, minScore.

set-active-clientSet active Roblox clientA

Route future Roblox tool calls to the specified connected client. Use list-clients first if you need available clientIds.

Inputs: clientId (required).

type-text-boxType into a TextBoxA

Enter text into a Roblox TextBox by path. Can simulate keystrokes or set Text directly based on useKeyPress.

Inputs: path (required), text (required), enter, useKeyPress.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, from execution (execute, execute-file, get-data-by-code) to remote spy management (ensure-remote-spy, block-remote, ignore-remote) to UI interaction (click-button, type-text-box) and exploration (get-descendants-tree, search-instances, script-grep, semantic-search-scripts). No two tools overlap in functionality.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case, such as block-remote, clear-remote-spy-logs, get-game-info, set-active-client. The naming is predictable and easy to understand.

    Tool Count5/5

    With 21 tools, the server covers a broad but well-scoped set of operations for Roblox client automation, including execution, remote spy, UI interaction, and exploration. The count feels appropriate and not overwhelming.

    Completeness5/5

    The tool surface provides comprehensive coverage for the server's purpose: execution (with and without return), remote spy lifecycle (ensure, read, clear, block, ignore), UI manipulation, script analysis, and instance exploration. There are no obvious gaps that would hinder common workflows.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with running Roblox game instances by inspecting the game hierarchy, reading client-side scripts, and executing Lua code directly within the Roblox client through a WebSocket bridge.
      4
      4
      30 npm
      -
    • F
      license
      B
      quality
      Not graded
      maintenance
      Bridges AI assistants with Roblox game environments in real-time via a Lua client and WebSocket connection. Enables AI tools like Claude to navigate instances, execute scripts, monitor remote events, and interact with the Roblox API through natural language.
      13
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI coding tools to control Roblox Studio for workspace exploration, instance manipulation, and script management. It provides tools for playtesting, scene rendering, and integration with the Roblox Creator Store.
      6
      9
      MIT