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

# Roblox Executor MCP Server

An advanced Model Context Protocol (MCP) server that allows AI agents to interact with running Roblox game clients. This server enables code execution, script decompilation, instance hierarchy querying, remote event spying and firing, and real-time log streaming.

---

## 🚀 Key Features

* **Code Execution** — Run Luau code on the client dynamically, with optional return value yielding.
* **Script Inspection** — Decompile scripts, search across sources, and perform semantic searches.
* **Instance Search & Manipulation** — Use CSS-like selectors, traverse the instance hierarchy tree, and query dynamic properties/attributes.
* **Remote Spy & Fire** — Intercept, log, block, ignore, and fire `RemoteEvents` / `RemoteFunctions` (backed by [Cobalt](https://github.com/notpoiu/cobalt)).
* **Real-Time Log Streaming** — Capture client console outputs dynamically via WebSockets and view them live.
* **GUI Interaction** — Automate input by clicking buttons and typing text into UI elements.
* **OS Integrations** — Retrieve list of Roblox processes and capture client window screenshots (Windows only).
* **Multi-Client Routing** — Coordinate between multiple running clients with automatic Primary/Secondary promotion and relaying.
* **Local Script Hub** — Save, load, and execute pre-configured Luau scripts.

---

## 🖥️ Local Web Dashboard

The Roblox Executor MCP includes a rich, responsive local web dashboard hosted at:
```text
http://localhost:16384/
```

Use the dashboard to monitor connected clients, debug executables, and inspect games:
1. **Console Tab** *(New)*: A real-time stream of the Roblox client console logs (`LogService.MessageOut`), color-coded by log levels: **Info (White)**, **Warning (Yellow)**, and **Error (Red)**.
2. **Executor Tab** *(New)*: A developer-focused suite to write Luau code directly, toggle **"Get Return Value"** to yield and print results, and instantly execute scripts saved in the `user-scripts/` hub.
3. **Tools Tab**: A control center to run all registered MCP tools manually and review inputs/outputs.
4. **Scripts Tab**: Explore local and decompiled scripts, search sources, index game hierarchies, and set up semantic vector search.

---

## 🛠️ Complete Tool Catalog

The server registers a comprehensive list of tools for connected AI agents:

### 1. Client Management
* `list-clients` — Lists all currently connected Roblox game clients.
* `set-active-client` — Selects the active target client for subsequent tool operations.

### 2. Execution Tools
* `execute` — Executes raw Luau code on the active Roblox client.
* `execute-file` — Executes a Luau file from the server's local path.
* `teleport-player` *(New)* — Relocates the player to specific coordinates, offsets, or target players.
* `set-player-property` *(New)* — Modifies character stats (e.g., WalkSpeed, JumpPower, HipHeight, Gravity) or toggles Noclip.

### 3. Inspection & Search Tools
* `get-script-content` — Retrieves the source/decompiled code of a specific script.
* `get-data-by-code` — Queries client metadata using a Luau lookup script.
* `get-console-output` — Returns the history of client console prints and warnings.
* `search-instances` — Finds instances using selectors or names.
* `get-descendants-tree` — Dumps the child hierarchy tree of a specific instance.
* `script-grep` — Performs text searches across all loaded script sources.
* `semantic-search-scripts` — Performs vector-based search on script contents (requires Ollama setup).
* `get-game-info` — Queries game details (e.g., PlaceId, JobId, Player count).
* `get-executor-environment` *(New)* — Returns a checklist of custom APIs supported by the connected Roblox executor (e.g., `getgc`, `hookfunction`).
* `get-instance-properties` *(New)* — Probes attributes, CollectionService tags, and properties of an instance dynamically.

### 4. Remote Spy & Network Tools
* `ensure-remote-spy` — Starts the Cobalt-backed remote spy pipeline.
* `get-remote-spy-logs` — Retreives captured remote calls.
* `clear-remote-spy-logs` — Clears captured logs.
* `block-remote` — Blocks a specific RemoteEvent or RemoteFunction.
* `ignore-remote` — Filters a remote out of the active log stream.
* `fire-remote` *(New)* — Fires a RemoteEvent or invokes a RemoteFunction. Supports dynamically evaluated arguments starting with `loadstring:`.

### 5. GUI & OS Tools
* `click-button` — Fires clicks on specific GUI buttons on the screen.
* `type-text-box` — Focuses and sends text inputs to game TextBoxes.
* `list-roblox-windows` — Lists active Roblox OS window handles.
* `screenshot-window` — Caps and saves screenshots of the game client (Windows only).

---

## 📋 Prerequisites

* **Node.js** ≥ 18
* **Bun** ≥ 1.3 (used for the interactive OpenTUI harness installer)
* **Roblox Executor** — Any executor supporting `loadstring`, `request`, and (preferably) `WebSocket`.

---

## ⚡ Quick Start

### 1. Clone the Repository
```bash
git clone https://github.com/notpoiu/roblox-executor-mcp.git
cd roblox-executor-mcp
```

### 2. Run the Harness Installer
The installer handles server building, configuration generation for your AI client of choice, and prints your loader script:
```bash
npm run install:harnesses
```

> [!TIP]
> If your terminal has issues rendering the interactive OpenTUI picker, run it in plain-text prompt mode:
> ```bash
> npm run install:harnesses -- --plain
> ```

To automatically place the Roblox loader into the `autoexec` folder of a detected executor (e.g. MacSploit, or supported Windows executors), run:
```bash
npm run getscript -- --autoexec
```

### 3. Connect from Roblox
Paste this script into your executor or place it in your `autoexec` folder:
```lua
local bridgeUrl = getgenv().BridgeURL or "localhost:16384"
loadstring(game:HttpGet("http://" .. bridgeUrl .. "/script.luau"))()
```

#### Optional Environment Configuration
Configure these globals *before* running the loader script to customize behavior:
```lua
getgenv().BridgeURL = "10.0.0.4:16384"                  -- Default: localhost:16384
getgenv().DisableWebSocket = true                        -- Forces HTTP fallback polling
getgenv().DisableInitialScriptDecompMapping = true       -- Skips initial project script indexing
```

---

## ⚙️ Client Configuration & Manual Setup

If you prefer to configure your AI interface manually, refer to the guides below:

| Client | Configuration Guide |
|---|---|
| **Cursor** | [Setup Guide](docs/setup-cursor.md) |
| **Claude Desktop** | [Setup Guide](docs/setup-claude-desktop.md) |
| **Claude Code** | [Setup Guide](docs/setup-claude-code.md) |
| **Codex CLI** | [Setup Guide](docs/setup-codex.md) |
| **Windsurf** | [Setup Guide](docs/setup-windsurf.md) |
| **Antigravity** | [Setup Guide](docs/setup-antigravity.md) |

---

## 🛠️ Developer Commands

Maintain, run, or update the server using these project scripts:

* **Build the project** (compiles TypeScript and copies assets to `dist/`):
  ```bash
  npm run build
  ```
* **Start the server**:
  ```bash
  npm run start
  ```
* **Update existing install** (pulls updates, stops running processes, and rebuilds):
  ```bash
  npm run update
  ```

---

## 🔒 Security & Safe Operation

> [!CAUTION]
> **This server allows arbitrary local code execution.** Only connect trusted AI clients. Port `16384` does not enforce authentication—**never expose this port to the public internet**. For cross-machine or LAN setups, secure connections with a local VPN or an SSH tunnel.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).