Universal Roblox Studio MCP Bridge

A pure-Python, standard-library-only Model Context Protocol bridge that connects an AI IDE (Claude Desktop, Cursor, Claude Code, Antigravity, OpenCode, Windsurf) to Roblox Studio's native StudioMCP daemon. It fixes the handshake, pipe-buffer, auto-update, version-selection, and session-rebinding bugs that make the stock setup unreliable.

Unofficial community tool — not affiliated with or endorsed by Roblox Corporation. It only launches Roblox's own local StudioMCP executable and edits local IDE config files; it opens no network listeners. Current release: v1.3.5 (CHANGELOG.md).

Quick start

1. Enable MCP in Roblox Studio File → Beta Features → check Model Context Protocol → restart Studio and open any place.

2. Install the bridge and write the IDE config

The installed command is roblox-studio-mcp (short alias) or roblox-studio-mcp-bridge. inject detects how it was installed, writes the right MCP-server entry into every AI IDE it finds, removes conflicting legacy entries, and prints a diagnostic report. Pick the entry style explicitly with inject --mode uvx|pip|repo if the auto-detection guesses wrong.

3. Restart your AI IDE (Claude Desktop, Cursor, Antigravity, OpenCode).

That's it. To remove it later: roblox-studio-mcp eject (or uninstall.bat / uninstall.command).

Source-checkout (--mode repo) only: the config points at the folder you cloned, so keep it where it is — if you move it, re-run inject. uvx and pip installs have no such dependency.

What it fixes

Pointing a modern AI IDE directly at Roblox's StudioMCP runs into several bugs:

How this compares

Requirements

• OS: Windows 10/11 or macOS. (The injector has a Linux fallback for Cursor/OpenCode/Antigravity, but the executable resolver only supports Windows and macOS install layouts.)
• Python: 3.8 or newer, on PATH as python.
• Roblox Studio with the Model Context Protocol beta feature enabled (see step 1 above).

How it works

flowchart TD
    Host["AI IDE / Agent<br/>Claude Desktop / Cursor / Antigravity / Claude Code"]
    Host -->|"JSON-RPC 2.0 (stdio)"| Loop

    subgraph BridgeEngine["Universal Roblox Studio MCP Bridge"]
        Loop["stdio event loop<br/>core/bridge.py"]
        Decoupler["Request-ID decoupler<br/>core/protocol.py"]
        Resolver["Newest-build resolver<br/>core/resolver.py"]
        Session["Self-healing session manager<br/>core/session.py"]
        Proc["Subprocess and async pipe drainers<br/>core/process.py"]
        Loop --> Decoupler
        Loop --> Resolver
        Loop --> Session
        Loop --> Proc
    end

    Proc -->|"local stdio pipes"| StudioMCP["Roblox StudioMCP daemon<br/>StudioMCP.exe"]
    StudioMCP -->|"local connection"| Studio["Roblox Studio<br/>active place and DataModel"]

The package is small and each module has one job:

Installation details

The bridge ships on PyPI as roblox-studio-mcp-bridge. inject detects how it is available and writes the matching config entry — force it with --mode:

Config entry format

// uvx / pip mode — no path dependency
{ "mcpServers": { "roblox_studio": {
  "command": "uvx",                                // or the python interpreter, for pip mode
  "args": ["roblox-studio-mcp-bridge", "run"],      // or ["-m", "roblox_studio_mcp", "run"]
  "env": { "PYTHONIOENCODING": "utf-8", "PYTHONUNBUFFERED": "1" }
} } }

// repo mode — bound to the clone, which must not move
{ "mcpServers": { "roblox_studio": {
  "command": "C:\\Path\\To\\python.exe",
  "args": ["-m", "roblox_studio_mcp", "run"],
  "cwd": "C:\\Path\\To\\roblox-studio-mcp-bridge",
  "env": { "PYTHONIOENCODING": "utf-8", "PYTHONUNBUFFERED": "1",
           "PYTHONPATH": "C:\\Path\\To\\roblox-studio-mcp-bridge" }
} } }

• Existing servers in the file are preserved. The original file is copied to *.backup.json before every write; an unparseable file is copied to *.corrupt.bak and repaired.
• Roblox's own Roblox_Studio entry (its mcp.bat launcher, or the direct-StudioMCP form it writes on macOS) is automatically purged, and its broken mcp.bat is rewritten in place with a working launcher (original saved as mcp.bat.roblox-bak).

Auto-inject targets

inject / eject / scrub understand --target all|claude|cursor|opencode|antigravity (default all):

Hosts that are not auto-injected (e.g. Claude Code, Windsurf) still work — add an mcpServers.roblox_studio entry manually using the JSON shown above.

CLI commands

With the package installed, use the roblox-studio-mcp command (or python -m roblox_studio_mcp, or uvx roblox-studio-mcp-bridge) from anywhere:

# Run the stdio bridge server (auto-scrubs Roblox's entry + repairs mcp.bat on startup)
python -m roblox_studio_mcp run

# Diagnostics: list StudioMCP candidates and verify all IDE configurations
python -m roblox_studio_mcp doctor

# Inject config into all detected AI IDEs
python -m roblox_studio_mcp inject --target all

# Scrub: remove Roblox's own broken entry + repair its mcp.bat (leaves other servers alone)
python -m roblox_studio_mcp scrub --target all

# Eject: remove the roblox_studio entry from all IDEs
python -m roblox_studio_mcp eject --target all

python -m roblox_studio_mcp with no subcommand is equivalent to run. python -m roblox_studio_mcp --version prints the version.

Configuration / environment variables

Troubleshooting

Start with the doctor — it does not modify anything:

python -m roblox_studio_mcp doctor

Development

git clone https://github.com/Cpleasance/roblox-studio-mcp-bridge
cd roblox-studio-mcp-bridge
pip install -e ".[dev]"

python -m pytest        # run the test suite
ruff check .            # lint
ruff format .           # format

The runtime code is standard-library only and must stay Python 3.8 compatible. See CONTRIBUTING.md for coding conventions and the PR process. For security issues, see SECURITY.md.

License

MIT License — see LICENSE. Author: Cory Pleasance.