roblox-studio-mcp

通过 MCP 在 Roblox Studio 中工作

Roblox Studio 自带一个内置 MCP 服务（stdio）。借助它，Agent 可以探索打开的 place、编辑脚本、在编辑/服务端/客户端上下文中运行 Luau、进行试玩测试、读取输出、捕获视口，以及模拟玩家输入。这是验证 Roblox 改动而非靠猜测的最快方式。

设置

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

# 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

{ "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。

工具

分组	工具
会话	list_roblox_studios（每次调用都需要一个 studio_id）、get_studio_state（游玩状态、可用的 DataModel）
探索	search_game_tree（按路径/类/关键词、深度过滤）、inspect_instance（属性、特性、子项）、script_search（按名称模糊搜索）、script_grep（跨脚本文本搜索，≤ 50 条命中）、script_read（点路径如 game.ServerScriptService.Main、行范围）
编辑	multi_edit（对单个脚本进行多处编辑，若不存在则创建；datamodel_type = Edit）
运行	execute_luau（datamodel_type = Edit、Server 或 Client；返回结果或错误）
试玩测试	start_stop_play、get_console_output、screen_capture（可选相机位置/注视点）、character_navigation、user_keyboard_input、user_mouse_input
资源	search_asset（Creator Store / 库存）、insert_asset、upload_image、store_image、generate_mesh、generate_material、generate_procedural_model + wait_job_finished
委派	subagent（explore 或 playtest 类型，用于多步调查）
知识	http_get（Roblox 文档、API 参考、Cloud 文档）、skill（Roblox 编写的技能：调试、设备模拟、文档搜索、性能分析、场景分析、单元测试）

工作循环

1. 定位：list_roblox_studios → 选择 studio_id；get_studio_state。用 search_game_tree（限制深度：先服务）绘制项目结构，然后用 script_grep/script_search 查找该功能。
2. 先读后写：script_read 每一个你将改动的脚本及其引用方。在 Studio 中编辑前，检查是否有 Rojo/Script Sync 设置（见下文）。
3. 编辑：使用 multi_edit（精确、最小改动；保持现有风格）。在 Edit 上下文中用 execute_luau 创建实例/特性/标签 —— 以这种方式做出的改动是对 place 的真实编辑。
4. 静态验证：重新读取脚本；对于纯模块，用 execute_luau 快速检查 （在 Edit 中 require 该模块并调用函数）。
5. 试玩测试：start_stop_play（开始）→ 等待 → get_console_output 查看错误 → 用 character_navigation / 输入工具驱动场景 → 在 Server/Client 中 execute_luau 断言状态 → screen_capture 进行视觉检查 → start_stop_play（停止）。完成后务必停止试玩。
6. 报告改动了什么、验证了什么（以及什么没有验证）。

-- 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")

经验法则

• 在 Edit 中执行 execute_luau 会修改场景：探索时优先使用只读查询，并将有意的更改批量整合到一个清晰的脚本中。使用 ChangeHistoryService 录制（TryBeginRecording/FinishRecording），以便用户可以将你的编辑作为一步撤销。
• 在运行 play（Server/Client 上下文）期间所做的更改在 play 停止时会被丢弃——请在 Edit 中进行编辑。
• Rojo 项目：文件系统是唯一事实来源——编辑磁盘上的文件，让 Rojo 同步，并使用 MCP 进行 playtest/检查。通过 multi_edit 编辑已同步的脚本会被覆盖。Script Sync 项目双向同步，因此任意一侧均可，但不要同时编辑同一脚本的两侧。
• 保持 search_game_tree 查询范围狭窄（路径 + 深度）；大型场景会产生巨大的输出。
• 多个 Studio 窗口：始终传入正确的 studio_id；告诉用户你修改了哪个场景。
• 从 Creator Store 插入的资产可能包含脚本：在保留它们之前进行检查（search_game_tree + script_read）；删除意外的脚本（免费模型中常见后门）。
• 没有证据就不要声称成功：引用控制台输出、断言结果或截图。

Roblox 编写的技能和转换

Studio 通过 skill 工具暴露 Roblox 编写的技能（例如 rbx-debug、rbx-perf-profiling、rbx-scene-analysis、rbx-unit-test、rbx-docs-search、rbx-device-simulator-lua）。Roblox 还发布了一个官方 streaming conversion 技能（/rbx-convert-to-streaming，可从"Techniques and conversion" streaming 文档下载），它通过此 MCP 服务运行；请先备份场景。

相关技能

roblox-testing（测试运行器）、roblox-performance（性能分析）、roblox-tooling（Rojo/Script Sync）、roblox-architecture（事物的归属位置）、roblox-code-review。