Back to Details

roblox-studio-mcp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Working in Roblox Studio through MCP

通过 MCP 在 Roblox Studio 中工作

Roblox Studio ships a built-in MCP server (stdio). With it, an agent can explore the open place, edit scripts, run Luau in edit/server/client contexts, playtest, read the Output, capture the viewport, and simulate player input. It is the fastest way to verify Roblox changes instead of guessing.
Roblox Studio 自带一个 内置 MCP server（stdio）。借助它，Agent 可以探索已打开的 place， 编辑脚本，在 Edit/Server/Client 上下文中运行 Luau，进行 playtest，读取 Output，截取视口画面， 并模拟玩家输入。这是验证 Roblox 改动的最快方式，无需依赖猜测。

Setup

设置

  1. Latest Studio → open Assistant → … → Manage MCP Servers → enable Enable Studio as MCP server.
  2. Use Quick connect (Claude Code, Claude Desktop, Codex CLI, Cursor, Gemini CLI, VS Code, Antigravity) or configure the client manually:
OSCommand
macOS
/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP
Windows
cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat
bash
undefined
  1. 最新版 Studio → 打开 Assistant → … → Manage MCP Servers → 启用 Enable Studio as MCP server。
  2. 使用 Quick connect（Claude Code、Claude Desktop、Codex CLI、Cursor、Gemini CLI、VS Code、Antigravity） 或手动配置客户端：
操作系统命令
macOS
/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP
Windows
cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat
bash
undefined

Claude Code

Claude Code

claude mcp add Roblox_Studio -- /Applications/RobloxStudio.app/Contents/MacOS/StudioMCP claude mcp add Roblox_Studio -- cmd.exe /c "%LOCALAPPDATA%\Roblox\mcp.bat" # Windows

```json
{ "mcpServers": { "Roblox_Studio": { "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP" } } }
Client-specific config (Codex 
config.toml
, OpenCode 
opencode.json
, Cursor/VS Code 
mcp.json
): references/client-setup.md. A green indicator in Manage MCP Servers confirms the connection. Only connect clients you trust: they can read and modify your places.
claude mcp add Roblox_Studio -- /Applications/RobloxStudio.app/Contents/MacOS/StudioMCP claude mcp add Roblox_Studio -- cmd.exe /c "%LOCALAPPDATA%\Roblox\mcp.bat" # Windows

```json
{ "mcpServers": { "Roblox_Studio": { "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP" } } }
客户端专属配置（Codex 
config.toml
、OpenCode 
opencode.json
、Cursor/VS Code 
mcp.json
）： references/client-setup.md。Manage MCP Servers 中出现绿色指示灯 即表示连接成功。仅连接你信任的客户端：它们可以读取和修改你的 place。

Tools

工具

GroupTools
Session
list_roblox_studios
(every call takes a 
studio_id
), 
get_studio_state
(play state, available DataModels)
Explore
search_game_tree
(filter by path/class/keyword, depth), 
inspect_instance
(properties, attributes, children), 
script_search
(fuzzy by name), 
script_grep
(text across scripts, ≤ 50 hits), 
script_read
(dot path like 
game.ServerScriptService.Main
, line ranges)
Edit
multi_edit
(several edits to one script, creates it if missing; 
datamodel_type = Edit
)
Run
execute_luau
(
datamodel_type
= 
Edit
, 
Server
, or 
Client
; returns the result or error)
Playtest
start_stop_play
, 
get_console_output
, 
screen_capture
(optional camera position/look-at), 
character_navigation
, 
user_keyboard_input
, 
user_mouse_input
Assets
search_asset
(Creator Store / inventory), 
insert_asset
, 
upload_image
, 
store_image
, 
generate_mesh
, 
generate_material
, 
generate_procedural_model
+ 
wait_job_finished
Delegation
subagent
(
explore
or 
playtest
types for multi-step investigations)
Knowledge
http_get
(Roblox docs, API reference, Cloud docs), 
skill
(Roblox-authored skills: debugging, device simulation, docs search, profiling, scene analysis, unit tests)
分组工具
会话
list_roblox_studios
（每次调用都需要传入 
studio_id
）、
get_studio_state
（播放状态、可用 DataModels）
探索
search_game_tree
（按 path/class/keyword 筛选，可指定 depth）、
inspect_instance
（properties、attributes、children）、
script_search
（按名称模糊搜索）、
script_grep
（在脚本中搜索文本，≤ 50 个命中）、
script_read
（点路径，如 
game.ServerScriptService.Main
，支持行范围）
编辑
multi_edit
（对一个脚本进行多项编辑；不存在时则创建；
datamodel_type = Edit
）
运行
execute_luau
（
datamodel_type
= 
Edit
、
Server
或 
Client
；返回结果或错误）
Playtest
start_stop_play
、
get_console_output
、
screen_capture
（可选相机位置/look-at）、
character_navigation
、
user_keyboard_input
、
user_mouse_input
资产
search_asset
（Creator Store / inventory）、
insert_asset
、
upload_image
、
store_image
、
generate_mesh
、
generate_material
、
generate_procedural_model
+ 
wait_job_finished
委派
subagent
（
explore
或 
playtest
类型，用于多步骤调查）
知识
http_get
（Roblox docs、API reference、Cloud docs）、
skill
（由 Roblox 编写的 skills：调试、设备模拟、文档搜索、性能分析、场景分析、单元测试）

The working loop

工作流程

  1. Orient: 
    list_roblox_studios
    → pick 
    studio_id
    ; 
    get_studio_state
    . Map the project with 
    search_game_tree
    (depth-limited: services first), then 
    script_grep
    /
    script_search
    for the feature.
  2. Read before writing: 
    script_read
    every script you'll touch and its requirers. Check for a Rojo/Script Sync setup (see below) before editing in Studio.
  3. Edit with 
    multi_edit
    (exact, minimal edits; keep existing style). Create instances/attributes/ tags with 
    execute_luau
    in 
    Edit
    context — changes made this way are real edits to the place.
  4. Verify statically: re-read the script; for pure modules, 
    execute_luau
    a quick check (
    require
    the module in 
    Edit
    and call functions).
  5. Playtest: 
    start_stop_play
    (start) → wait → 
    get_console_output
    for errors → drive the scenario with 
    character_navigation
    / input tools → 
    execute_luau
    in 
    Server
    /
    Client
    to assert state → 
    screen_capture
    for visual checks → 
    start_stop_play
    (stop). Always stop play when done.
  6. Report what changed and what was verified (and what wasn't).
luau
-- Example execute_luau (Server context during play): assert game state instead of eyeballing.
local Players = game:GetService("Players")
local results = {}
for _, player in Players:GetPlayers() do
	local leaderstats = player:FindFirstChild("leaderstats")
	local coins = leaderstats and leaderstats:FindFirstChild("Coins")
	table.insert(results, `{player.Name}: {if coins and coins:IsA("IntValue") then coins.Value else "missing"}`)
end
return table.concat(results, "\n")
  1. 定位：
    list_roblox_studios
    → 选择 
    studio_id
    ；
    get_studio_state
    。使用 
    search_game_tree
    梳理项目结构（限制 depth：先查各项 services），再通过 
    script_grep
    /
    script_search
    查找目标功能。
  2. 写入前先读取：读取你将要修改的每个脚本及其调用方。编辑 Studio 前，检查是否配置了 Rojo/Script Sync（见下文）。
  3. 编辑：使用 
    multi_edit
    进行精确、最小化的编辑，并保持现有风格。通过 
    execute_luau
    在 
    Edit
    环境中创建 instances/attributes/tags——以此方式进行的更改是对 place 的真实编辑。
  4. 静态验证：重新读取脚本；对于纯 module，在 
    Edit
    中 
    require
    该 module 并调用 functions， 使用 
    execute_luau
    执行快速检查。
  5. Playtest：
    start_stop_play
    （启动）→ 等待 → 通过 
    get_console_output
    检查错误 → 使用 
    character_navigation
    /input tools 驱动测试场景 → 在 
    Server
    /
    Client
    中执行 
    execute_luau
    以 assert 状态 → 使用 
    screen_capture
    进行视觉检查 → 
    start_stop_play
    （停止）。完成后务必停止 play。
  6. 报告修改了哪些内容、验证了哪些内容，以及哪些内容未经验证。
luau
-- Example execute_luau (Server context during play): assert game state instead of eyeballing.
local Players = game:GetService("Players")
local results = {}
for _, player in Players:GetPlayers() do
	local leaderstats = player:FindFirstChild("leaderstats")
	local coins = leaderstats and leaderstats:FindFirstChild("Coins")
	table.insert(results, `{player.Name}: {if coins and coins:IsA("IntValue") then coins.Value else "missing"}`)
end
return table.concat(results, "\n")

Rules of thumb

经验法则

  • execute_luau
    in 
    Edit
    mutates the place: prefer read-only queries while exploring, and batch intentional changes into one clear script. Use 
    ChangeHistoryService
    recording (
    TryBeginRecording
    / 
    FinishRecording
    ) so the user can undo your edit as one step.
  • Changes made during play (Server/Client contexts) are discarded when play stops — edit in 
    Edit
    .
  • Rojo projects: the file system is the source of truth — edit files on disk, let Rojo sync, and use MCP to playtest/inspect. Editing synced scripts via 
    multi_edit
    gets overwritten. Script Sync projects sync both ways, so either side works, but don't edit the same script in both at once.
  • Keep 
    search_game_tree
    queries narrow (path + depth); large places produce huge outputs.
  • Multiple Studio windows: always pass the right 
    studio_id
    ; tell the user which place you touched.
  • Inserted assets from the Creator Store can contain scripts: inspect them (
    search_game_tree
    + 
    script_read
    ) before keeping them; remove unexpected scripts (backdoors are common in free models).
  • Don't claim success without evidence: cite console output, assertion results, or screenshots.
  • execute_luau
    在 
    Edit
    中会修改 place：探索时优先使用只读查询，并将有意进行的更改批量合并到一个清晰的脚本中。使用 
    ChangeHistoryService
    recording（
    TryBeginRecording
    / 
    FinishRecording
    ），让用户可以将编辑作为一步撤销。
  • play 期间（Server/Client 上下文）所做的更改会在停止 play 时被丢弃——应在 
    Edit
    中编辑。
  • Rojo 项目：文件系统是 source of truth——在磁盘上编辑文件，让 Rojo 同步，并通过 MCP 进行 playtest/检查。通过 
    multi_edit
    编辑已同步的脚本会被覆盖。Script Sync 项目会双向同步，因此任一侧都可编辑，但不要同时在两侧编辑同一脚本。
  • 保持 
    search_game_tree
    查询范围狭窄（path + depth）；大型 place 会产生巨量输出。
  • 多个 Studio 窗口：始终传入正确的 
    studio_id
    ；告知用户修改了哪个 place。
  • 从 Creator Store 插入的资产可能包含 scripts：保留前先检查它们（
    search_game_tree
    + 
    script_read
    ）；删除意外的 scripts（免费模型中常见 backdoors）。
  • 没有证据时不要宣称成功：应引用 console output、assertion results 或 screenshots 作为依据。

Roblox-authored skills and conversions

Roblox 编写的 skills 与转换工具

Studio exposes Roblox-authored skills through the 
skill
tool (e.g. 
rbx-debug
, 
rbx-perf-profiling
, 
rbx-scene-analysis
, 
rbx-unit-test
, 
rbx-docs-search
, 
rbx-device-simulator-lua
). Roblox also publishes an official streaming conversion skill (
/rbx-convert-to-streaming
, downloadable from the "Techniques and conversion" streaming docs) that runs through this MCP server; back up the place first.
Studio 通过 
skill
工具提供由 Roblox 编写的 skills（例如 
rbx-debug
、
rbx-perf-profiling
、 
rbx-scene-analysis
、
rbx-unit-test
、
rbx-docs-search
、
rbx-device-simulator-lua
）。Roblox 还 发布了官方 streaming conversion skill（
/rbx-convert-to-streaming
，可从 streaming 文档中的 “Techniques and conversion”下载），该 skill 通过此 MCP server 运行；请先备份 place。

Related skills

相关 skills

roblox-testing
(test runners), 
roblox-performance
(profiling), 
roblox-tooling
(Rojo/Script Sync), 
roblox-architecture
(where things belong), 
roblox-code-review
.
roblox-testing
（test runners）、
roblox-performance
（profiling）、
roblox-tooling
（Rojo/Script Sync）、 
roblox-architecture
（各项内容应放在何处）、
roblox-code-review
。