Roblox Studio MCP Gateway
Uses Roblox public APIs for engine documentation lookup and Creator Store catalog/asset search.
Provides tools for inspecting and editing Roblox Studio places, Explorer instances, Luau scripts, instance properties, selections, playtests, diagnostics, and assets through the Roblox Studio bridge and plugin.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Roblox Studio MCP Gateway Preview shrinking the lobby spawn pad to 20x20."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
Place and Explorer |
|
Luau scripts |
|
Playtesting |
|
Diagnostics |
|
Assets and models |
|
Reference and snapshots |
|
Related MCP server: Roblox Studio MCP Server
Requirements
Python 3.10 or later for the gateway.
Node.js 22 or later for
@chrrxs/robloxstudio-mcp3.1.0.Roblox Studio with the matching 3.1.0
MCPPlugin.rbxmxplugin.
Quick start
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.exeto install and.venv\Scripts\mcp-roblox.exeto launch the gateway.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_DIRbefore running it.npx --yes @chrrxs/robloxstudio-mcp@3.1.0 --auto-install-pluginRestart 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 |
|
Command on Linux and macOS |
|
Command on Windows |
|
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 |
|
| HTTP address of the upstream bridge. |
|
| Path to the bridge token file. |
| Vinegar's default Studio plugins directory | Directory where the gateway checks for |
Configure overrides in your MCP client's environment settings for the local server.
Editing and playtesting
roblox_edit,roblox_script_set, androblox_replacepreview writes by default. Review the preview before applying a change. Script line edits and asset imports write directly.roblox_backupsaves 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_execrequiresconfirm: truefor server and client playtest execution. Run the bridge on loopback and use it with a trusted local MCP client.roblox_toolboxcan 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_soloorroblox_multiplayerto start a session.roblox_playtestcollects a screenshot and logs, then returns a heuristic verdict. Arollbackverdict is advisory.roblox_capturesupportsscene,memory,script, andmicro. Profiler captures require a connected server peer and are capped at 15 seconds for scripts and 5 seconds for MicroProfiler. Local.rbxmimports are capped at 37.5 MiB.To test network conditions, start a multiplayer session and pass
great,good, orpoorexplicitly toroblox_network. The gateway targets the first client.
Troubleshooting
Symptom | What to check |
| Start the pinned bridge and check the address in |
| 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 |
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 -qLicense
Available Tools
33 toolsroblox_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_searchC
Search instances in the open Studio place.
Inputs: query (required), scope. 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
Scored across 33 tools
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.
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.
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.
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
Related MCP Connectors
Build, test, publish and manage real MCP servers from APIs with a live developer studio.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Hosted MCP for Remotion videos: search Remocn components, read docs, plan a video, preview it.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI tools to read the Roblox Studio game tree, edit scripts, insert models, and run playtests via the Studio MCP interface.37 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT
- AlicenseAqualityBmaintenanceEnables 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.92MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm1MIT