roblox-mcp

roblox-mcp

官方来源：

• https://create.roblox.com/docs/en-us/studio/mcp
• https://create.roblox.com/docs/en-us/ai/build
• https://create.roblox.com/docs/en-us/scripting/sync
• https://modelcontextprotocol.io/docs/getting-started/intro

官方 Roblox Studio MCP 服务可让已连接的 AI 客户端检查和编辑已打开的场景。它提供用于脚本、实例、Luau 执行、资源和游戏测试的工具。

Studio MCP 服务是什么

Roblox Studio 使用 stdio 传输实现了 Model Context Protocol (MCP) 服务。该服务以本地进程的形式运行在你的计算机上，并将受支持的 AI 客户端发来的请求转发到当前 Studio 会话。它是编辑器中的 Agent 与 Studio 之间的桥梁：Script Sync 负责在磁盘和 Studio 之间同步文件，而 MCP 负责其他所有操作（Explorer 选择、实例检查、脚本编辑、Luau 执行、游戏模式、输入模拟和资源插入）。

先决条件

1. 最新版 Roblox Studio。通过启动器更新，或从 Creator Hub 下载。
2. 支持 MCP 的 AI 客户端。Cursor、搭配 Claude Code 的 VS Code、Claude Desktop、Codex CLI、Gemini CLI、Antigravity，或任何支持 stdio 传输的客户端。
3. 已登录 Studio 的 Roblox 账户。
4. Git（推荐），用于基于文件的工作流。

在 Studio 中启用服务

1. 打开 Studio，并加载要让 Agent 操作的场景。
2. 打开 Assistant（右上角的按钮）。
3. 点击 ⋯ → Manage MCP Servers。
4. 开启 Enable Studio as MCP server。
5. 面板会显示快速连接选项和手动配置片段。客户端连接后会出现绿色指示灯。

如果看不到 MCP 选项，请在更新到最新版后重启 Studio。

连接客户端

选择适合你所用客户端的方法：

快速连接支持 Antigravity、Codex CLI、Claude Code、Claude Desktop、Cursor、Gemini CLI 和 Visual Studio Code。

1. 在 Studio 中：Assistant → ⋯ → Manage MCP Servers → Quick connect。
2. 开启已安装的客户端。
3. 如果工具没有立即显示，请重启客户端。

对于读取 mcp.json 或类似配置文件的客户端，请参阅 references/setup-and-connection.md，其中提供了适用于各操作系统的复制粘贴配置。

对于需要原始 CLI 命令的客户端，请参阅 references/setup-and-connection.md，其中提供了适用于 Windows 和 macOS 的命令。

连接后，使用以下内容进行验证：

使用 Roblox MCP 读取 Roblox Studio 中当前的游戏树。列出 Workspace 中的内容。

使用 MCP 工具可以做什么

该服务提供多个类别的工具。当前工具名称和使用指南请参阅 references/tool-reference.md。

类别	示例
脚本	script_read、multi_edit、script_search、script_grep
数据模型	search_game_tree、inspect_instance、subagent（explore）
Luau 执行	execute_luau
资源生成与插入	generate_mesh、generate_material、generate_procedural_model、wait_job_finished、search_asset、insert_asset、upload_image、store_image
游戏测试	start_stop_play、get_studio_state、get_console_output、screen_capture、subagent（playtest）
输入模拟	character_navigation、user_keyboard_input、user_mouse_input
文档	http_get、skill
实例发现	list_roblox_studios；在后续调用中传入 studio_id

使用 MCP 和 Script Sync

Script Sync 会将磁盘上的文件夹（ServerScriptService/、ReplicatedStorage/、StarterPlayerScripts/ 等）映射到 Studio 服务，因此你在本地编辑的 .luau 文件会自动显示在 Studio 中。MCP 可处理 Script Sync 无法触及的所有内容：编辑 StarterGui、插入模型、运行命令、进行游戏测试以及检查实例。

典型的 Agent 工作循环：

1. 通过 Script Sync 编辑磁盘文件，以处理可复用的模块和脚本。
2. 使用 MCP 检查实例、运行 Luau 代码片段、启动游戏模式，并捕获输出和屏幕截图。
3. 使用 MCP 编辑位于 Script Sync 未覆盖的容器中的脚本（例如 StarterGui）。

完整设置说明和入门项目布局请参阅 references/script-sync-integration.md。

多实例处理

调用 list_roblox_studios 以发现已连接的窗口、其 Studio 实例 ID 和 place ID。没有 place ID 的本地 place 会按名称列出。在后续每次工具调用中都传入所选实例的 studio_id；不要依赖共享的活动窗口，也不要根据对象路径推断目标。窗口关闭或目标发生变化时，重新列出实例。

安全与信任

MCP 客户端可以读取和修改已打开的 place。请像对待任何特权集成一样对待 MCP 连接：

• 只连接你信任的客户端。
• 在测试 place 或受版本控制的项目中工作。
• 发布前检查 Agent 的修改。
• 将 .rbxlx 和其他 place 文件排除在 Git 之外（使用入门 .gitignore）。
• 不使用时断开连接或禁用 MCP 服务。
• 将 execute_luau 视为特权代码：它可以发布 place、写入 DataStore、发出 HTTP 请求，以及访问已加载到 Studio 中的凭据。

完整的安全检查清单和故障排除步骤请参阅 references/security-and-troubleshooting.md。

验证清单

• Studio 已更新且已启用 MCP。
• 重启后，AI 客户端会显示 Roblox MCP 工具。
• script_read 或 search_game_tree 会返回当前 place 结构。
• Script Sync 会将预期的服务文件夹映射到磁盘（如果使用基于文件的工作流）。
• execute_luau 可以运行简单的 print 并返回输出。
• start_stop_play 可以成功进入和退出游戏模式。

脚本

• scripts/MCPReadyChecker.lua：可通过 execute_luau 运行的诊断代码片段，用于验证 Script Sync 状态和基本模型健康状况。
• scripts/StudioModelProbe.lua：可复用的实用工具，用于汇总游戏树，可作为 Agent 探索提示词的参考模式。

后续步骤

1. 确认先决条件，并在 Studio 中启用 MCP。
2. 使用快速连接，或按照 references/setup-and-connection.md 中的手动配置连接客户端。
3. 通过简单的树读取或 execute_luau 调用验证连接。
4. 如果使用基于文件的工作流，请按照 references/script-sync-integration.md 设置 Script Sync。
5. 使用工具参考编写精准的 Agent 提示词，并使用安全指南确保工作流安全。

参考索引

• script-sync-integration.md：结合磁盘上的文件、Studio MCP 编辑和游戏测试。
• security-and-troubleshooting.md：排查 MCP 连接失败或检查 Studio 访问权限。
• setup-and-connection.md：启用 Studio MCP，并在 Windows 或 macOS 上连接客户端。
• tool-reference.md：选择 Studio MCP 工具并确定目标 Studio 实例。