How

Command

Notes

uvx (recommended)

uvx roblox-studio-mcp-bridge inject

No install step. Needs uv.

pip

pip install roblox-studio-mcp-bridge then roblox-studio-mcp inject

Standard Python install.

Double-click

install.bat (Windows) / install.command (macOS)

Runs a source checkout in place — clone first.

Problem in the stock setup

Impact

How this bridge solves it

server/discover handshake crash

Some hosts send a server/discover probe before initialize; StudioMCP requires initialize first and drops the connection.

The bridge answers server/discover itself by proxying tools/list, so discovery never reaches the daemon out of order.

Broken mcp.bat ('else' is not recognized…)

Roblox's generated %LOCALAPPDATA%\Roblox\mcp.bat puts ) and else on separate lines — invalid batch. It fails the moment the hard-coded version-<hash> path goes stale (i.e. after any Studio update).

inject / scrub / bridge startup rewrite mcp.bat with a correct, version-independent launcher (original kept as mcp.bat.roblox-bak), and strip Roblox's own Roblox_Studio entry.

stderr pipe deadlock ("Working…" freeze)

StudioMCP writes enough to its stderr pipe to fill the OS buffer; with nobody draining it, the daemon blocks and the host hangs forever.

Dedicated daemon threads continuously drain both stdout and stderr; stderr lines land in a bounded in-memory ring buffer.

Roblox auto-updates wipe configs

Studio updates roughly weekly and rewrites its own launcher/config files.

The IDE config points at python -m roblox_studio_mcp, which the Roblox updater never touches. The bridge also auto-scrubs re-injected Roblox_Studio entries and re-repairs mcp.bat on every startup.

Stale version-* folder selection

Naive lookups pick an old version-<hash> directory instead of the current build.

The resolver scans every known install root, prefers the folder that also contains the Studio Beta binary, and breaks ties by newest modification time.

Place / session disconnects

Switching places or restarting Studio breaks the tool connection; calls then fail silently.

The session manager auto-discovers Studio instances via list_roblox_studios, injects the resolved studio_id into every tool call, and transparently re-resolves and retries when it detects a disconnect or stale id.

Requests that hang the host

An internal failure used to leave the host waiting on a response id it would never receive.

Every failed request now returns a JSON-RPC -32603 error so the host fails fast instead of hanging.

Stock StudioMCP + mcp.bat

Minimal single-file fixes

This bridge

server/discover crash fixed

❌

✅

✅

stderr pipe-deadlock fixed

❌

✅

✅

Survives Roblox's weekly auto-update

❌ (config overwritten)

⚠️ re-run installer each update

✅ auto-scrubs + re-repairs mcp.bat on every startup

Picks the newest Studio build

❌

⚠️ first match

✅ Beta-companion + newest mtime

Self-healing session rebind on disconnect

❌

❌

✅ re-resolves + retries

Failed request can't hang the host

❌

❌

✅ always returns -32603

Clients wired up by inject

—

1

Claude Desktop, Cursor, OpenCode, Antigravity (+ manual for Claude Code / Windsurf)

Install

copy files

copy files

uvx / pip / source

Tests / CI

—

—

150+ tests, GitHub Actions

Module

Responsibility

core/resolver.py

Locates the StudioMCP executable. Honors ROBLOX_STUDIO_MCP_PATH / STUDIO_MCP_PATH, otherwise scans the Roblox install roots and returns the best candidate (Studio Beta companion present, then newest mtime).

core/process.py

Spawns StudioMCP as a child process. One daemon thread reads stdout and resolves per-id response futures; another drains stderr into a deque ring buffer so the OS pipe never fills. A lock serializes all writes to the child's stdin.

core/protocol.py

JSON-RPC 2.0 helpers, error-code constants, the negotiated MCP protocol version (2024-11-05), and RequestIdDecoupler, which hands out collision-free internal ids for requests the bridge originates.

core/session.py

Resolves the target Studio instance with list_roblox_studios, caches its studio_id, and injects it into each forwarded tool call (unless the caller supplied one). On a detected disconnect or stale id it drops the cache and re-resolves, retrying up to 3 times with backoff.

core/bridge.py

The stdio event loop. Reads host requests line by line, answers initialize / ping / server/discover / resources/list / prompts/list locally, forwards tools/list and tools/call, and guarantees a response (or -32603) for every request that has an id. Installs guarded signal handlers (SIGINT, SIGTERM, SIGBREAK).

core/_log.py

Shared logger. Everything diagnostic goes to stderr; stdout is reserved for the JSON-RPC stream. Level comes from ROBLOX_STUDIO_MCP_LOG_LEVEL (default WARNING).

injector/config_injector.py

Detects installed IDEs and injects / ejects the roblox_studio MCP server entry, backing up any file it touches.

cli.py

Argument parsing for the run / doctor / inject / scrub / eject subcommands.

--mode

Config entry

Use when

uvx

uvx roblox-studio-mcp-bridge run

You have uv; nothing to install or keep.

pip

<python> -m roblox_studio_mcp run

Installed with pip install roblox-studio-mcp-bridge.

repo

same, plus cwd + PYTHONPATH to the checkout

Running a git clone in place (what install.bat does).

auto (default)

repo from a checkout, else pip

—

Target

Config file(s)

claude

Windows: %APPDATA%\Claude\claude_desktop_config.jsonmacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

cursor

~/.cursor/mcp.json and …/Cursor/User/globalStorage/roam.cursor-mcp/mcp.json

opencode

~/.opencode/mcp.json

antigravity

~/.gemini/antigravity/mcp_config.json

Variable

Purpose

Default

ROBLOX_STUDIO_MCP_PATH

Absolute path to a StudioMCP executable, or to a folder containing one. Skips auto-discovery entirely.

(unset — auto-discover)

STUDIO_MCP_PATH

Checked only if ROBLOX_STUDIO_MCP_PATH is unset. Same meaning.

(unset)

ROBLOX_STUDIO_MCP_LOG_LEVEL

Diagnostic log verbosity on stderr: DEBUG, INFO, WARNING, ERROR.

WARNING

PYTHONPATH

Set by the injector to the repo root so python -m roblox_studio_mcp resolves without an install.

(set by inject)

PYTHONIOENCODING / PYTHONUNBUFFERED

Set by the injector to utf-8 / 1 for clean, unbuffered stdio.

(set by inject)

Symptom

Likely cause / fix

doctor prints "No StudioMCP.exe found"

Roblox Studio is not installed, or the Model Context Protocol beta feature is off. Enable it, restart Studio, re-run doctor. As a last resort set ROBLOX_STUDIO_MCP_PATH to the executable.

IDE shows a red MCP Error on Roblox_Studio — 'else' is not recognized as an internal or external command / '"%B/..\StudioMCP.exe"' / expect initialized request

That is Roblox's own broken mcp.bat, not this bridge. Run roblox-studio-mcp inject (or scrub) once and restart the IDE — the bridge removes the Roblox_Studio entry and rewrites mcp.bat. Its own roblox_studio entry is what you use.

Bridge exits immediately with a [roblox-studio-mcp] message on stderr

Same as above — StudioMCP could not be located. The message includes the remediation steps.

Tools appear in the IDE but every call returns "Roblox Studio is not connected"

Open a place in Studio and make sure the MCP beta feature is enabled. The session manager retries a few times, then returns this error.

IDE does not see the server at all

Confirm inject reported the right config file, then fully restart the IDE. Run doctor to see which config paths exist.

It broke after moving or deleting the repo folder

The config entry's cwd / PYTHONPATH still point at the old path. Re-run python -m roblox_studio_mcp inject from the new location.

Need more detail

Set ROBLOX_STUDIO_MCP_LOG_LEVEL=DEBUG (in the config entry's env, or your shell) and check the IDE's MCP log — all bridge logging goes to stderr.

Config used to get wiped by Roblox updates

Fixed in this bridge: the entry runs python -m …, which the updater never rewrites. Re-run inject once and you are done.