Back to Details

roblox-mcp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

roblox-mcp

roblox-mcp

Official sources:
The official Roblox Studio MCP server lets a connected AI client inspect and edit an open place. It provides tools for scripts, instances, Luau execution, assets, and playtesting.
官方来源：
官方 Roblox Studio MCP server 允许已连接的 AI 客户端检查和编辑打开的 place。它提供用于脚本、instance、Luau 执行、asset 和 playtesting 的工具。

What the Studio MCP server is

Studio MCP server 是什么

Roblox Studio implements a Model Context Protocol (MCP) server using 
stdio
transport. The server runs as a local process on your machine and proxies requests from a supported AI client into the active Studio session. It is the bridge between your editor's agent and Studio: Script Sync handles disk-to-Studio file syncing, while MCP handles everything else (Explorer selection, instance inspection, script editing, Luau execution, play mode, input simulation, and asset insertion).
Roblox Studio 基于 
stdio
transport 实现了一个 Model Context Protocol（MCP） server。该 server 作为本地进程运行在你的机器上，并将受支持 AI 客户端的请求代理到活动的 Studio 会话中。它是编辑器中的 agent 与 Studio 之间的桥梁：Script Sync 负责从磁盘到 Studio 的文件同步，而 MCP 负责其他所有工作（Explorer 选中操作、instance 检查、脚本编辑、Luau 执行、play mode、输入模拟和 asset 插入）。

Prerequisites

先决条件

  1. Latest Roblox Studio. Update through the launcher or download from the Creator Hub.
  2. An MCP-capable AI client. Cursor, VS Code with Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Antigravity, or any client that supports 
    stdio
    transport.
  3. A Roblox account signed into Studio.
  4. Git (recommended) for the file-based workflow.
  1. 最新版本的 Roblox Studio。通过启动器更新，或从 Creator Hub 下载。
  2. 支持 MCP 的 AI 客户端。Cursor、配合 Claude Code 使用的 VS Code、Claude Desktop、Codex CLI、Gemini CLI、Antigravity，或任何支持 
    stdio
    transport 的客户端。
  3. 已登录 Studio 的 Roblox 账号。
  4. Git（推荐），用于基于文件的工作流。

Enabling the server in Studio

在 Studio 中启用 server

  1. Open Studio and load the place you want the agent to work on.
  2. Open Assistant (button in the upper right).
  3. Click ⋯ → Manage MCP Servers.
  4. Turn on Enable Studio as MCP server.
  5. The panel shows quick-connect options and manual configuration snippets. A green indicator appears when a client connects.
If you do not see MCP options, restart Studio after updating to the latest version.
  1. 打开 Studio 并加载希望 agent 操作的 place。
  2. 打开 Assistant（右上角的按钮）。
  3. 点击 ⋯ → Manage MCP Servers。
  4. 开启 Enable Studio as MCP server。
  5. 面板会显示快速连接选项和手动配置片段。客户端连接后会出现绿色指示器。
如果更新后仍看不到 MCP 选项，请重启 Studio。

Connecting your client

连接客户端

Choose the method that matches your client:
Quick connect supports Antigravity, Codex CLI, Claude Code, Claude Desktop, Cursor, Gemini CLI, and Visual Studio Code.
  1. In Studio: Assistant → ⋯ → Manage MCP Servers → Quick connect.
  2. Turn on your installed client.
  3. Restart the client if the tools do not appear immediately.
For clients that read an 
mcp.json
or similar config file, see references/setup-and-connection.md for per-OS, copy-paste configurations.
For clients that need a raw CLI command, see references/setup-and-connection.md for Windows and macOS commands.
After connecting, verify with:
Use the Roblox MCP to read the current game tree in Roblox Studio. List what's in Workspace.
选择与你的客户端匹配的方法：
Quick connect 支持 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，其中提供了针对各 OS、可直接复制的配置。
对于需要原始 CLI 命令的客户端，请参阅 references/setup-and-connection.md，其中提供了 Windows 和 macOS 命令。
连接后，使用以下提示进行验证：
使用 Roblox MCP 读取 Roblox Studio 中当前的游戏树。列出 Workspace 中的内容。

What you can do with the MCP tools

可以使用 MCP 工具完成什么

The server exposes tools in several categories. The current tool names and usage guidance are in references/tool-reference.md.
CategoryExamples
Scripts
script_read
, 
multi_edit
, 
script_search
, 
script_grep
Data model
search_game_tree
, 
inspect_instance
, 
subagent
(
explore
)
Luau execution
execute_luau
Asset generation & insertion
generate_mesh
, 
generate_material
, 
generate_procedural_model
, 
wait_job_finished
, 
search_asset
, 
insert_asset
, 
upload_image
, 
store_image
Playtesting
start_stop_play
, 
get_studio_state
, 
get_console_output
, 
screen_capture
, 
subagent
(
playtest
)
Input simulation
character_navigation
, 
user_keyboard_input
, 
user_mouse_input
Documentation
http_get
, 
skill
Instance discovery
list_roblox_studios
; pass 
studio_id
on subsequent calls
该 server 公开了多个类别的工具。当前工具名称和使用指南位于 references/tool-reference.md。
类别示例
脚本
script_read
, 
multi_edit
, 
script_search
, 
script_grep
数据模型
search_game_tree
, 
inspect_instance
, 
subagent
(
explore
)
Luau 执行
execute_luau
Asset 生成与插入
generate_mesh
, 
generate_material
, 
generate_procedural_model
, 
wait_job_finished
, 
search_asset
, 
insert_asset
, 
upload_image
, 
store_image
Playtesting
start_stop_play
, 
get_studio_state
, 
get_console_output
, 
screen_capture
, 
subagent
(
playtest
)
输入模拟
character_navigation
, 
user_keyboard_input
, 
user_mouse_input
文档
http_get
, 
skill
Instance 发现
list_roblox_studios
；在后续调用中传入 
studio_id

Work with MCP and Script Sync

结合使用 MCP 和 Script Sync

Script Sync maps folders on disk (
ServerScriptService/
, 
ReplicatedStorage/
, 
StarterPlayerScripts/
, etc.) to Studio services, so 
.luau
files you edit locally appear in Studio automatically. MCP covers everything Script Sync cannot reach: editing 
StarterGui
, inserting models, running commands, playtesting, and inspecting instances.
Typical agent loop:
  1. Edit disk files through Script Sync for reusable modules and scripts.
  2. Use MCP to inspect instances, run Luau snippets, start play mode, and capture output/screenshots.
  3. Use MCP to edit scripts that live in containers not covered by Script Sync (for example, 
    StarterGui
    ).
See references/script-sync-integration.md for the full setup and a starter-project layout.
Script Sync 将磁盘上的文件夹（
ServerScriptService/
、
ReplicatedStorage/
、
StarterPlayerScripts/
等）映射到 Studio service，因此在本地编辑的 
.luau
文件会自动出现在 Studio 中。MCP 覆盖 Script Sync 无法触及的所有内容：编辑 
StarterGui
、插入 model、执行命令、playtesting 和检查 instance。
典型的 agent 工作流：
  1. 通过 Script Sync 编辑磁盘文件，以管理可复用的 module 和 script。
  2. 使用 MCP 检查 instance、运行 Luau 片段、启动 play mode，并捕获输出和截图。
  3. 使用 MCP 编辑 Script Sync 未覆盖容器中的 script（例如 
    StarterGui
    ）。
有关完整设置和 starter project 布局，请参阅 references/script-sync-integration.md。

Multi-instance handling

多 instance 处理

Call 
list_roblox_studios
to discover connected windows, their Studio instance IDs, and place IDs. Local places without a place ID are listed by name. Pass the selected instance's 
studio_id
on every subsequent tool call; do not rely on a shared active window or infer the target from an object path. Re-list instances when a window closes or the target changes.
调用 
list_roblox_studios
可发现已连接的窗口、其 Studio instance ID 和 place ID。没有 place ID 的本地 place 会按名称列出。在每次后续工具调用中传入所选 instance 的 
studio_id
；不要依赖共享的活动窗口，也不要根据 object path 推断目标。当窗口关闭或目标发生变化时，请重新列出 instance。

Security and trust

安全与信任

MCP clients can read and modify your open places. Treat MCP connections like any privileged integration:
  • Only connect clients you trust.
  • Work on test places or version-controlled projects.
  • Review agent edits before publishing.
  • Keep 
    .rbxlx
    and other place files out of Git (use the starter 
    .gitignore
    ).
  • Disconnect or disable the MCP server when it is not in use.
  • Treat 
    execute_luau
    as privileged code: it can publish places, write to DataStores, make HTTP requests, and access credentials loaded in Studio.
See references/security-and-troubleshooting.md for the full security checklist and troubleshooting steps.
MCP 客户端可以读取和修改你打开的 place。请将 MCP 连接视为任何其他特权集成：
  • 仅连接你信任的客户端。
  • 在测试 place 或受版本控制的项目中工作。
  • 发布前检查 agent 的编辑内容。
  • 不要将 
    .rbxlx
    和其他 place 文件提交到 Git（使用 starter 
    .gitignore
    ）。
  • 不使用时断开或禁用 MCP server。
  • 将 
    execute_luau
    视为特权代码：它可以发布 place、写入 DataStores、发起 HTTP 请求，以及访问 Studio 中加载的凭据。
有关完整安全检查清单和故障排除步骤，请参阅 references/security-and-troubleshooting.md。

Verification checklist

验证清单

  • Studio is updated and MCP is enabled.
  • AI client shows the Roblox MCP tools after restart.
  • script_read
    or 
    search_game_tree
    returns the current place structure.
  • Script Sync maps the expected service folders to disk (if using file-based workflow).
  • execute_luau
    can run a simple 
    print
    and return output.
  • start_stop_play
    enters/exits play mode successfully.
  • Studio 已更新且 MCP 已启用。
  • AI 客户端在重启后显示 Roblox MCP 工具。
  • script_read
    或 
    search_game_tree
    返回当前 place 结构。
  • Script Sync 将预期的 service 文件夹映射到磁盘（如果使用基于文件的工作流）。
  • execute_luau
    可以运行简单的 
    print
    并返回输出。
  • start_stop_play
    可以成功进入和退出 play mode。

Scripts

脚本

  • scripts/MCPReadyChecker.lua
    : a diagnostic snippet you can run with 
    execute_luau
    to verify Script Sync status and basic model health.
  • scripts/StudioModelProbe.lua
    : a reusable utility for summarizing the game tree, useful as a pattern for agent exploration prompts.
  • scripts/MCPReadyChecker.lua
    ：可通过 
    execute_luau
    运行的诊断片段，用于验证 Script Sync 状态和基本模型运行状况。
  • scripts/StudioModelProbe.lua
    ：用于汇总游戏树的可复用 utility，可作为 agent 探索提示词的参考模式。

How to proceed

后续操作

  1. Confirm prerequisites and enable MCP in Studio.
  2. Connect your client using quick connect or the manual config in references/setup-and-connection.md.
  3. Verify the connection with a simple tree-read or 
    execute_luau
    call.
  4. If using a file-based workflow, set up Script Sync per references/script-sync-integration.md.
  5. Use the tool reference to craft precise agent prompts and the security guide to keep the workflow safe.
<!-- catalog:references:start -->
  1. 确认先决条件并在 Studio 中启用 MCP。
  2. 使用 Quick connect 或 references/setup-and-connection.md 中的手动配置连接客户端。
  3. 使用简单的 tree-read 或 
    execute_luau
    调用验证连接。
  4. 如果使用基于文件的工作流，请按照 references/script-sync-integration.md 设置 Script Sync。
  5. 使用工具参考编写精准的 agent 提示词，并遵循安全指南以确保工作流安全。
<!-- catalog:references:start -->

Reference index

参考索引

  • script-sync-integration.md: Combine files on disk with Studio MCP edits and playtests.
  • security-and-troubleshooting.md: Investigate MCP connection failures or review Studio access.
  • setup-and-connection.md: Enable Studio MCP and connect a client on Windows or macOS.
  • tool-reference.md: Choose a Studio MCP tool and identify the target Studio instance.
<!-- catalog:references:end -->
  • script-sync-integration.md：将磁盘上的文件与 Studio MCP 编辑和 playtest 结合起来。
  • security-and-troubleshooting.md：排查 MCP 连接故障或检查 Studio 访问权限。
  • setup-and-connection.md：在 Windows 或 macOS 上启用 Studio MCP 并连接客户端。
  • tool-reference.md：选择 Studio MCP 工具并确定目标 Studio instance。
<!-- catalog:references:end -->