roblox-studio-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roblox Studio MCP

The official Roblox Studio MCP server is built into Studio. It provides direct access to the data model, script editing, code execution, asset generation, and playtesting. This skill documents every tool and the patterns for using them reliably.

官方Roblox Studio MCP服务器内置在Studio中，它提供对数据模型、脚本编辑、代码执行、资产生成和游戏测试的直接访问。本技能文档记录了每个工具以及可靠使用它们的模式。

Available Tools

可用工具

Scripts

脚本工具

Tool	What it does
`script_read`	Read scripts by dot-notation path (e.g. `game.ServerScriptService.MyScript` ). Supports line ranges.
`multi_edit`	Apply multiple edits to a script. Creates the script if the path doesn't exist.
`script_search`	Fuzzy search for scripts by name. Returns up to 10 results.
`script_grep`	Search for a string pattern across all scripts. Returns up to 50 matches.

工具	功能
`script_read`	通过点符号路径读取脚本（例如 `game.ServerScriptService.MyScript` ），支持行范围选择。
`multi_edit`	对脚本应用多项编辑操作。若路径不存在则创建脚本。
`script_search`	按名称模糊搜索脚本，最多返回10个结果。
`script_grep`	在所有脚本中搜索字符串模式，最多返回50个匹配项。

Asset & Content Generation

资产与内容生成

Tool	What it does
`generate_mesh`	Generate a textured 3D mesh from a description.
`generate_material`	Generate a custom material or texture.
`generate_procedural_model`	Generate procedural models that scale and adapt automatically.
`insert_from_creator_store`	Insert assets, plugins, and models from the Creator Store.

工具	功能
`generate_mesh`	根据描述生成带纹理的3D网格。
`generate_material`	生成自定义材质或纹理。
`generate_procedural_model`	生成可自动缩放和适配的程序化模型。
`insert_from_creator_store`	从创作者商店插入资产、插件和模型。

Data Model Exploration

数据模型探索

Tool	What it does
`explore_subagent`	Investigate the place in parallel, returns a compact summary.
`search_game_tree`	Explore instance hierarchy as flat JSON. Filter by path, type, keywords.
`inspect_instance`	Detailed info about a specific instance: properties, attributes, children summary.

工具	功能
`explore_subagent`	并行探查场景，返回精简摘要。
`search_game_tree`	将实例层级结构作为扁平化JSON进行探索，支持按路径、类型、关键词过滤。
`inspect_instance`	获取特定实例的详细信息：属性、特性、子项摘要。

Luau Execution

Luau代码执行

Tool	What it does
`execute_luau`	Run Luau code in Studio. Returns result or error.

工具	功能
`execute_luau`	在Studio中运行Luau代码，返回结果或错误信息。

Playtesting

游戏测试

Tool	What it does
`start_stop_play`	Start or stop playtesting.
`console_output`	Retrieve output logs while the game is running.
`screen_capture`	Capture the current Studio viewport in Play mode.
`playtest_subagent`	Spawn a test character that runs through gameplay scenarios.

工具	功能
`start_stop_play`	启动或停止游戏测试。
`console_output`	检索游戏运行时的输出日志。
`screen_capture`	捕获Play模式下当前Studio视口的画面。
`playtest_subagent`	生成测试角色，运行游戏玩法场景。

Player Input Simulation

玩家输入模拟

Tool	What it does
`character_navigation`	Move the player character to a position or instance.
`keyboard_input`	Simulate key presses, holds, and text input.
`mouse_input`	Simulate mouse clicks, movement, and scrolling.

工具	功能
`character_navigation`	将玩家角色移动到指定位置或实例处。
`keyboard_input`	模拟按键按下、按住和文本输入。
`mouse_input`	模拟鼠标点击、移动和滚动操作。

Session Management

会话管理

Tool	What it does
`list_roblox_studios`	List all connected Studio instances (name, ID, active status).
`set_active_studio`	Set which Studio instance receives subsequent tool calls.

工具	功能
`list_roblox_studios`	列出所有已连接的Studio实例（名称、ID、活跃状态）。
`set_active_studio`	设置后续工具调用指向哪个Studio实例。

MCP Reliability Patterns

MCP可靠性模式

Statelessness

无状态性

execute_luau

is stateless. Every call is a blank slate. Variables and references do not persist between calls.

luau

-- ALWAYS re-acquire references at the start of every execute_luau call
local model = workspace:FindFirstChild("MyModel")
if not model then
    model = Instance.new("Model")
    model.Name = "MyModel"
    model.Parent = workspace
end

execute_luau

是无状态的，每次调用都是全新环境，变量和引用不会在调用之间持久化。

luau

-- 每次execute_luau调用开始时，务必重新获取引用
local model = workspace:FindFirstChild("MyModel")
if not model then
    model = Instance.new("Model")
    model.Name = "MyModel"
    model.Parent = workspace
end

Silent Failures

静默失败

execute_luau

may return success even when objects weren't created (parent doesn't exist, name collision, etc). Always verify after creation:

luau

-- Create then verify
local part = Instance.new("Part")
part.Name = "Floor"
part.Parent = workspace.MapRoot

-- Verify it exists
local check = workspace.MapRoot:FindFirstChild("Floor")
print(check and "OK" or "FAILED: Floor not created")

execute_luau

可能在对象未创建成功时仍返回成功（如父对象不存在、名称冲突等）。创建后务必进行验证：

luau

-- 创建后验证
local part = Instance.new("Part")
part.Name = "Floor"
part.Parent = workspace.MapRoot

-- 验证对象是否存在
local check = workspace.MapRoot:FindFirstChild("Floor")
print(check and "OK" or "FAILED: Floor not created")

Script Truncation

脚本截断

When writing scripts via

multi_edit

execute_luau

with

script.Source = ...

, long scripts may silently truncate. For scripts over ~300 lines:

Split into logical chunks
Write each chunk separately using string concatenation
After writing, read back the last 10-20 lines to verify no truncation

luau

-- Chunked write pattern
local s = game.ServerScriptService.MyScript
local part1 = [=[
-- chunk 1: services and config
local Players = game:GetService("Players")
...
]=]
local part2 = [=[
-- chunk 2: main logic
...
]=]
s.Source = part1 .. part2

当通过

multi_edit

或

execute_luau

使用

script.Source = ...

编写脚本时，长脚本可能会被静默截断。对于超过约300行的脚本：

将脚本拆分为逻辑块
使用字符串拼接分别写入每个块
写入完成后，读取最后10-20行以验证未发生截断

luau

-- 分块写入模式
local s = game.ServerScriptService.MyScript
local part1 = [=[
-- 块1：服务与配置
local Players = game:GetService("Players")
...
]=]
local part2 = [=[
-- 块2：主逻辑
...
]=]
s.Source = part1 .. part2

Batching

批量操作

Part creation: 10-20 parts per call (safe), 25-50 with loops (risky)
Script writes: one script per call for reliability
Property changes: batch related changes in one call
Verification: always verify after creation batches

部件创建：每次调用创建10-20个部件（安全），循环创建25-50个有风险
脚本写入：每次调用写入一个脚本以保证可靠性
属性修改：将相关修改批量放在一次调用中
验证：批量创建后务必进行验证

Ground Truth Rule

真实数据规则

Never guess coordinates, sizes, or property values from chat history. If you need current state, READ it:

luau

local part = workspace.MapRoot:FindFirstChild("Tower")
if part then
    print("Position:", part.Position)
    print("Size:", part.Size)
    print("CFrame:", part.CFrame)
end

永远不要从聊天历史中猜测坐标、尺寸或属性值。如果需要当前状态，请读取：

luau

local part = workspace.MapRoot:FindFirstChild("Tower")
if part then
    print("Position:", part.Position)
    print("Size:", part.Size)
    print("CFrame:", part.CFrame)
end

Workflows

工作流程

Script Development

脚本开发

Explore — Use
```
search_game_tree
```
to understand existing structure
Read — Use
```
script_read
```
to understand existing code before modifying
Write — Use
```
multi_edit
```
to create or modify scripts
Verify — Use
```
script_read
```
to confirm the write succeeded
Test — Use
```
start_stop_play
```
+
```
console_output
```
to test

探索 — 使用
```
search_game_tree
```
了解现有结构
读取 — 修改前使用
```
script_read
```
了解现有代码
编写 — 使用
```
multi_edit
```
创建或修改脚本
验证 — 使用
```
script_read
```
确认写入成功
测试 — 使用
```
start_stop_play
```
+
```
console_output
```
进行测试

Building Geometry

几何构建

Plan — Use
```
search_game_tree
```
to see what exists
Build — Use
```
execute_luau
```
to create parts (see roblox-building skill)
Verify — Use
```
execute_luau
```
to count parts and check properties
Visual check — Use
```
screen_capture
```
in play mode to see the result

规划 — 使用
```
search_game_tree
```
查看现有内容
构建 — 使用
```
execute_luau
```
创建部件（参考roblox-building技能）
验证 — 使用
```
execute_luau
```
统计部件数量并检查属性
视觉检查 — 在Play模式下使用
```
screen_capture
```
查看结果

Debugging

调试

Reproduce —
```
start_stop_play
```
to enter play mode
Observe —
```
console_output
```
to read errors/warnings
Inspect —
```
inspect_instance
```
or
```
execute_luau
```
to check runtime state
Fix —
```
multi_edit
```
to patch the script
Retest —
```
start_stop_play
```
again

复现 — 使用
```
start_stop_play
```
进入Play模式
观察 — 使用
```
console_output
```
读取错误/警告信息
检查 — 使用
```
inspect_instance
```
或
```
execute_luau
```
检查运行时状态
修复 — 使用
```
multi_edit
```
修补脚本
重新测试 — 再次使用
```
start_stop_play
```

Playtesting

游戏测试

Start play mode with
```
start_stop_play
```
Navigate with
```
character_navigation
```
Interact with
```
keyboard_input
```
/
```
mouse_input
```
Observe with
```
console_output
```
and
```
screen_capture
```
Stop with
```
start_stop_play
```

使用
```
start_stop_play
```
启动Play模式
使用
```
character_navigation
```
导航
使用
```
keyboard_input
```
/
```
mouse_input
```
进行交互
使用
```
console_output
```
和
```
screen_capture
```
观察
使用
```
start_stop_play
```
停止测试

MCP Mode Detection

MCP模式检测

Different MCP servers provide different tool sets. Detect what's available:

Official Roblox MCP (built into Studio):

execute_luau

multi_edit

script_read

search_game_tree

start_stop_play

generate_mesh

, etc.

Community MCP (Chrrxs/robloxstudio-mcp):
```
execute_luau
```
,
```
get_file_tree
```
,
```
grep_scripts
```
,
```
create_build
```
, plus per-peer execution.
No MCP: Pure code generation only. Provide copy-paste-ready scripts.

Adapt your approach based on what tools are actually available. If a tool call fails with "not found", fall back gracefully.

不同的MCP服务器提供不同的工具集，需检测可用工具：

官方Roblox MCP（内置在Studio中）：

execute_luau

、

multi_edit

、

script_read

、

search_game_tree

、

start_stop_play

、

generate_mesh

等。

社区MCP（Chrrxs/robloxstudio-mcp）：
```
execute_luau
```
、
```
get_file_tree
```
、
```
grep_scripts
```
、
```
create_build
```
，以及点对点执行功能。
无MCP：仅支持纯代码生成，提供可直接复制粘贴的脚本。

根据实际可用工具调整方法。如果工具调用返回“未找到”错误，请优雅降级处理。

Setup Reference

设置参考

Windows

Windows系统

json

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": ["/c", "%LOCALAPPDATA%\\Roblox\\mcp.bat"]
    }
  }
}

json

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": ["/c", "%LOCALAPPDATA%\\Roblox\\mcp.bat"]
    }
  }
}

macOS

macOS系统

json

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"
    }
  }
}

json

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"
    }
  }
}

Enable in Studio

在Studio中启用

Open Assistant
Click ... > Manage MCP Servers
Turn on "Enable Studio as MCP server"

Quick connect supports: Codex CLI, Claude Code, Claude Desktop, Cursor, Gemini CLI, VS Code.

打开助手（Assistant）
点击... > 管理MCP服务器（Manage MCP Servers）
开启“将Studio作为MCP服务器启用”（Enable Studio as MCP server）

快速连接支持：Codex CLI、Claude Code、Claude Desktop、Cursor、Gemini CLI、VS Code。