Skip to main content
Glama
Roblox Studio MCP Gateway

Roblox Studio MCP Gateway

by camilin7483

Roblox Studio MCP Gateway

mcp-roblox is a Python Model Context Protocol (MCP) server for Roblox Studio. It works with MCP clients that can launch a local server over stdio. Use it to inspect a place, edit Luau and instance properties, work with Creator Store assets, and diagnose playtests.

The gateway adds an edit planner, dry runs for common writes, and a playtest summary based on runtime logs. It uses Chrrxs's Roblox Studio bridge and plugin to interact with Studio, and calls Roblox's public APIs for engine documentation and catalog search.

flowchart LR
    Client["MCP client"] <-->|stdio| Gateway[Python MCP gateway]
    Gateway <-->|Local HTTP| Bridge[Chrrxs bridge]
    Bridge <--> Studio[Roblox Studio plugin]
    Gateway -.->|Docs and asset search| APIs[Public Roblox APIs]

Tools

The gateway exposes 33 tools.

Group

Tools

Status and planning

roblox_status, roblox_ensure_ready, roblox_plan

Place and Explorer

roblox_search, roblox_read, roblox_edit, roblox_attrs, roblox_tree, roblox_place, roblox_class, roblox_selection

Luau scripts

roblox_script_get, roblox_script_set, roblox_script_edit, roblox_script_lines, roblox_grep, roblox_replace, roblox_exec

Playtesting

roblox_solo, roblox_multiplayer, roblox_breakpoints, roblox_input, roblox_playtest, roblox_network, roblox_device

Diagnostics

roblox_capture, roblox_profile

Assets and models

roblox_toolbox, roblox_build, roblox_import, roblox_export

Reference and snapshots

roblox_docs, roblox_backup

Related MCP server: Roblox Studio MCP Server

Requirements

  • Python 3.10 or later for the gateway.

  • Node.js 22 or later for @chrrxs/robloxstudio-mcp 3.1.0.

  • Roblox Studio with the matching 3.1.0 MCPPlugin.rbxmx plugin.

Quick start

  1. From the repository directory, install the Python gateway in its own virtual environment.

    python -m venv .venv
    .venv/bin/python -m pip install .

    On Windows, use .venv\Scripts\python.exe to install and .venv\Scripts\mcp-roblox.exe to launch the gateway.

  2. Start the pinned bridge in a separate terminal and keep it running. The command installs the matching Studio plugin. For a custom plugin directory, set MCP_PLUGINS_DIR before running it.

    npx --yes @chrrxs/robloxstudio-mcp@3.1.0 --auto-install-plugin
  3. Restart Roblox Studio, open a place, and verify the connection in Plugins → MCP Server.

Configure your MCP client

Add a local stdio server using the absolute path to the installed executable. The client starts the Python gateway. The Studio bridge runs separately.

Field

Value

Name

roblox

Command on Linux and macOS

/path/to/project/.venv/bin/mcp-roblox

Command on Windows

C:\path\to\project\.venv\Scripts\mcp-roblox.exe

Arguments

None

Example for Cursor in mcp.json. Replace the executable path.

{
  "mcpServers": {
    "roblox": {
      "type": "stdio",
      "command": "/path/to/project/.venv/bin/mcp-roblox"
    }
  }
}

Use the same executable in other clients that support stdio. Cursor · VS Code with Copilot · OpenCode

Call roblox_status and check for plugin_connected: true. Try a read-only request such as “Describe the open place and list the top-level instances.”

Configuration

Environment variable

Default

Purpose

ROBLOX_BRIDGE_URL

http://127.0.0.1:58741

HTTP address of the upstream bridge.

ROBLOX_BRIDGE_TOKEN_FILE

~/.robloxstudio-mcp/auth-token

Path to the bridge token file.

MCP_PLUGINS_DIR

Vinegar's default Studio plugins directory

Directory where the gateway checks for MCPPlugin.rbxmx. Set this to the active plugins folder when using another Studio installation or Wine prefix.

Configure overrides in your MCP client's environment settings for the local server.

Editing and playtesting

  • roblox_edit, roblox_script_set, and roblox_replace preview writes by default. Review the preview before applying a change. Script line edits and asset imports write directly.

  • roblox_backup saves a dated JSON snapshot of the project's structure to ~/.cache/mcp-roblox/backups/. Save a Studio copy of the place for full restoration.

  • roblox_exec requires confirm: true for server and client playtest execution. Run the bridge on loopback and use it with a trusted local MCP client.

  • roblox_toolbox can preview models and delegates sanitized insertion to the plugin. Each call handles up to five insertions. Third-party assets require the matching permission in Studio.

  • Use roblox_solo or roblox_multiplayer to start a session. roblox_playtest collects a screenshot and logs, then returns a heuristic verdict. A rollback verdict is advisory.

  • roblox_capture supports scene, memory, script, and micro. Profiler captures require a connected server peer and are capped at 15 seconds for scripts and 5 seconds for MicroProfiler. Local .rbxm imports are capped at 37.5 MiB.

  • To test network conditions, start a multiplayer session and pass great, good, or poor explicitly to roblox_network. The gateway targets the first client.

Troubleshooting

Symptom

What to check

bridge: down

Start the pinned bridge and check the address in ROBLOX_BRIDGE_URL.

plugin_connected: false

Restart Studio after plugin installation. Verify that the plugin panel shows a connection and that both versions are 3.1.0.

MCP Server is missing

Check the plugins folder for the active Studio installation or Wine prefix. Set MCP_PLUGINS_DIR to the directory containing MCPPlugin.rbxmx.

No peer for the requested role

Start a playtest with the required server or client before calling role-specific tools.

Development

The test suite exercises validation and backend requests with mocks. The MCP SDK verified the stdio connection and tool catalog. Individual clients and a live Studio session still need verification.

.venv/bin/python -m pip install pytest
.venv/bin/python -m pytest -q

License

MIT

Available Tools

33 tools
roblox_attrsC

Get instance attributes.

Inputs: instance_path (required). Returns: result

roblox_backupB

Save current project structure to a dated JSON file.

Inputs: no named parameters. Returns: result

roblox_breakpointsC

List/set/clear script breakpoints.

Inputs: data, action. Returns: result

roblox_buildC

Generate a model from a text prompt via the bridge.

Inputs: prompt (required). Returns: result

roblox_captureD

scene | memory | script-profiler | micro-profiler.

Inputs: kind, seconds. Returns: result

roblox_classC

Class info: properties and events.

Inputs: class_name (required). Returns: result

roblox_deviceD

Device simulator state/set.

Inputs: action, device. Returns: result

roblox_docsC

Roblox engine reference docs (public, no Studio needed).

Inputs: name (required), category. Returns: result

roblox_editB

Set instance properties. Dry-run by default; back up first for real edits.

Inputs: instance_path (required), dry_run, properties. Returns: result

roblox_ensure_readyC

Plugin + bridge readiness (never launches processes).

Inputs: auto_launch. Returns: result

roblox_execC

Execute Luau in edit/server/client domain.

Inputs: source (required), domain, confirm. Returns: result

roblox_exportC

Export instance to .rbxm file (0600).

Inputs: instance_path (required), output. Returns: result

roblox_grepC

Grep script sources across the place.

Inputs: pattern (required), limit. Returns: result

roblox_importC

Import .rbxm file (max 37.5MB).

Inputs: file (required), parent. Returns: result

roblox_inputC

Simulate mouse/keyboard input in Studio.

Inputs: x, y, key, kind, +1 more. Returns: result

roblox_multiplayerC

Multiplayer playtest: start|add|leave|end|state.

Inputs: action, players. Returns: result

roblox_networkC

Set playtest network profile via Luau.

Inputs: profile. Returns: result

roblox_placeC

Place info: id, name, data model.

Inputs: no named parameters. Returns: result

roblox_planC

Deterministic ordered step list for an edit intent.

Inputs: intent (required). Returns: result

roblox_playtestC

Screenshot + runtime logs, then verify verdict.

Inputs: cursor, instance_id. Returns: result

roblox_profileC

Flag profiler readings over budget.

Inputs: micro_s, memory_mb. Returns: result

roblox_readB

Read properties of one instance by path.

Inputs: instance_path (required). Returns: result

roblox_replaceB

Find and replace across scripts. Dry-run by default.

Inputs: pattern (required), replacement (required), dry_run. Returns: result

roblox_script_editC

Replace first occurrence of old_string in a script.

Inputs: new_string (required), old_string (required), instance_path (required), start_line. Returns: result

roblox_script_getC

Get script source, optionally a line range.

Inputs: instance_path (required), end, start. Returns: result

roblox_script_linesC

Insert (after start_line) or delete (start_line..end_line) script lines.

Inputs: instance_path (required), action, content, end_line, +1 more. Returns: result

roblox_script_setC

Set script source. Dry-run by default.

Inputs: source (required), instance_path (required), dry_run. Returns: result

roblox_selectionB

Get selection, or set it when paths are given.

Inputs: paths. Returns: result

roblox_soloC

Start/stop solo playtest: mode play|stop.

Inputs: mode. Returns: result

roblox_statusC

Bridge + plugin status and effective env config.

Inputs: no named parameters. Returns: result

roblox_toolboxC

Toolbox gateway: insert ids, preview one asset, or search by query.

Inputs: limit, query, parent, insert_ids, +1 more. Returns: result

roblox_treeC

Project structure / file tree.

Inputs: path. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools have clearly distinct domains: import/export, scripts, playtest, profiling, input, docs, and device simulation are easy to tell apart. There is some overlap among roblox_search/roblox_grep, roblox_read/roblox_script_get/roblox_attrs, and the multiple script-editing tools, but descriptions provide enough distinction.

    Naming Consistency4/5

    All tools share a consistent roblox_ snake_case prefix, which makes the set predictable. However, names mix verb-first patterns (roblox_search, roblox_edit) with noun-only labels (roblox_tree, roblox_attrs, roblox_class, roblox_device), so the convention is not fully uniform.

    Tool Count3/5

    Thirty-three tools is heavy for a single MCP server and exceeds typical well-scoped ranges. The broad Studio gateway domain justifies many capabilities, but several script-edit and utility tools could likely be consolidated.

    Completeness4/5

    The surface covers an unusually broad Studio workflow: scripts, playtests, profiling, backups, import/export, docs, input simulation, multiplayer, network, and device simulation. Minor gaps remain, such as explicit instance creation/deletion and asset upload workflows, but most agent workflows are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to explore, edit, and automate Roblox Studio sessions locally, including browsing instance hierarchies, reading and modifying scripts, manipulating properties, creating instances, building terrain, and running playtests.
      1,057 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to drive a running Roblox Studio in real time over a single WebSocket, executing whole Luau programs, installing in-engine controllers, hot-patching scripts during live playtests, and receiving errors, assertions and other events as pushes. It also reaches Roblox Open Cloud for the open place and answers visual questions via a vision sidecar, exposing all of this through nine MCP tools.
      9
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Roblox Studio workflow automation beyond the built-in MCP, including opening places, managing assets via Open Cloud, safe Luau execution, and extracting place contents.
      68 npm
      1
      MIT