Raven Roblox MCP

A clean-room Roblox MCP bridge owned by N3zuui. Raven connects Codex and other MCP clients to an authorized live Roblox client through a private loopback-only daemon.

Install in one command

Requirements: Windows, Node.js 22+, Codex, Roblox, and an executor you are authorized to use.

npx -y github:valrinx/raven-roblox-mcp#main setup codex

The installer configures raven_roblox, starts the shared daemon, and prints this connector loader:

loadstring(game:HttpGet("http://127.0.0.1:17654/loader.luau"))()

Restart Codex once after initial setup. That is the entire installation—no clone, manual build, JSON editing, or separate server per chat.

Full Codex instructions: docs/CODEX.md. Problems: docs/TROUBLESHOOTING.md.

Why Raven is different

• One singleton daemon on 127.0.0.1:17654; every Codex chat/agent shares the same Roblox connection.
• A tiny STDIO proxy auto-starts or attaches to the daemon, eliminating port conflicts between agents.
• Accurate public place/experience names through cached MarketplaceService:GetProductInfo(game.PlaceId) metadata. Internal game.Name is exposed separately as dataModelName.
• Smooth-by-default connector: delayed startup, duplicate-launch guard, 2 ms cooperative work slices, 15-second heartbeat, and error-only console forwarding.
• Persistent per-user loopback token, so the connector automatically reconnects after daemon restarts.
• No telemetry, analytics, remote updater, external decompiler, or third-party Roblox API calls.
• Multiple Roblox clients with explicit active-client routing.
• Stateless Streamable HTTP MCP endpoint at /mcp, plus STDIO compatibility through the proxy.

Architecture

Codex chat A ─┐
Codex chat B ─┼─ STDIO proxies ── Streamable HTTP /mcp ─┐
Codex agent C ┘                                         │
                                                       ▼
                                            Raven daemon :17654
                                             │              │
                                  /loader.luau│              │/dashboard
                                             ▼              ▼
                                      Roblox connector   Browser UI

The daemon binds only to 127.0.0.1. Roblox receives the WebSocket token from the locally served connector; the token is never committed to Git.

Useful commands

# Configure Codex and start Raven
npx -y github:valrinx/raven-roblox-mcp#main setup codex

# Check server, MCP endpoint, and connected Roblox clients
npx -y github:valrinx/raven-roblox-mcp#main doctor

# Print only the Roblox loader
npx -y github:valrinx/raven-roblox-mcp#main loader

# Run the shared daemon visibly
npx -y github:valrinx/raven-roblox-mcp#main daemon

Dashboard: http://127.0.0.1:17654/dashboard

Capabilities

Live inspection and control

• Smart snapshots of game, player, nearby world, visible UI, and console
• Bounded instance search, property inspection, and hierarchy trees
• Visible UI dump and button activation
• Player state, teleport, interaction, waits, benchmarks, and screenshots
• Atomic typed property mutations with rollback
• Sequential or parallel batches of up to 50 operations

Authorized reverse engineering

• Script indexing, search, bytecode metadata, closure/constants/prototype inspection
• Luau v3-v12 bytecode parser with Roblox opcode-decoder auto-detection
• Instruction disassembly, register-oriented pseudo code, and control-flow graphs
• Evidence-scored cross-script dependency graph
• Bounded remote monitoring, argument-schema clustering, replay, and snapshots/diffs
• Runtime FPS, memory, ping, class-count, and traversal profiling

Pseudo code is an evidence-oriented representation, not claimed source recovery. Original identifiers, comments, formatting, and some high-level constructs do not exist in bytecode.

Recommended agent workflow

1. Call status, then list_clients.
2. Use smart_snapshot for initial orientation.
3. Narrow with query_instances, inspect_instance, get_tree, or dump_visible_ui.
4. Use batch for related reads.
5. Use mutation and remote-replay tools only when a live change is explicitly intended.

Build from source

git clone https://github.com/valrinx/raven-roblox-mcp.git
cd raven-roblox-mcp
npm ci
npm run check
npm run privacy:audit
npm audit

Run locally:

npm start

Security and scope

Raven is intended only for experiences, clients, and accounts you own or are explicitly authorized to test. execute_luau, remote replay, teleport, UI interaction, and property mutation can change live client state. See SECURITY.md for the complete security model.

Ownership and license

Raven's Roblox bridge, RPC protocol, tool schemas, security limits, bytecode analysis, and connector were developed as a clean-room implementation. Runtime dependencies are the official MCP SDK, Zod, and ws.

Copyright © 2026 N3zuui. Source-available for lawful use and private modification; redistribution, resale, relicensing, and removal of attribution are restricted. See LICENSE.