使用 Roblox Studio MCP 将 Roblox Studio 连接到 AI 助手

什么是 Roblox Studio MCP？

Roblox Studio MCP 是一个轻量级的 Node.js 和 TypeScript 服务器，通过模型上下文协议（Model Context Protocol）将 Roblox Studio 连接到 AI 编程助手。它可以让 AI 代理理解场景的对象层级、检查实例、创建或更新 Lua 脚本、修改属性，以及控制试玩会话。

该服务器通过 WebSockets 和 Studio 插件 API 与 Roblox Studio 通信。AI 客户端则通过 MCP，使用标准输入输出或受支持的适配器与服务器通信。

访问要求：你必须拥有要检查或修改的 Roblox 场景的编辑权限。

主要功能

• MCP 客户端支持：专为 Claude Desktop、Cursor、Cline 以及通过兼容适配器使用的 ChatGPT 设计。
• 对象树访问：读取当前 Roblox 场景的层级结构。
• Lua 脚本编辑：通过 AI 请求创建、读取和更新脚本。
• 属性检查：读取和修改实例属性。
• 试玩控制：从 AI 客户端启动和停止试玩会话。
• 只读模式：在探索项目时禁用破坏性操作。
• 会话发现：自动查找已打开的 Roblox Studio 会话。
• 轻量级架构：使用 Node.js、TypeScript、WebSockets 和 Lua Studio 插件。

可用的 MCP 工具

该服务器向已连接的 AI 代理提供以下操作：

• get_object_tree 返回当前场景的层级结构。
• get_instance 根据路径获取实例。
• get_properties 读取实例的属性。
• set_property 修改属性值。
• create_script 在指定父对象下创建 Lua 脚本。
• update_script 替换现有脚本的源代码。
• delete_instance 在禁用安全模式时删除对象。
• run_playtest 启动试玩会话。
• stop_playtest 停止当前试玩。

安装与设置

了解项目设置方式

README 提供了一种快速开始方式：下载 Core_Update_Pack 压缩包，解压后运行 ProjectFiles.exe，并按照屏幕上的说明操作。它还会直接通过 npx 配置 MCP 服务器。

安全提示：README 要求运行可执行文件并“注入脚本”，这与其另一处关于项目使用官方 Studio 插件 API 且不会注入代码的说明相矛盾。在运行任何下载的可执行文件之前，请核实代码仓库、源代码、发布文件和发布者。README 没有记录单独的手动插件安装流程。

配置 Claude Desktop 或 Cursor

对于 Claude Desktop，请打开 claude_desktop_config.json；对于 Cursor，请打开 MCP 设置。添加以下服务器定义：

{
  "mcpServers": {
    "roblox-studio": {
      "command": "npx",
      "args": ["-y", "roblox-studio-mcp"]
    }
  }
}

npx 命令要求安装包含 npm 和 npx 的 Node.js。保存配置并重启 AI 应用，使其加载服务器。

打开 Roblox 场景

1. 启动 Roblox Studio。
2. 打开一个你拥有编辑权限的场景。
3. 根据项目设置，确保项目的 Studio 端插件组件可用且已连接。
4. 保存 MCP 配置后，重启 Claude Desktop 或 Cursor。
5. 要求助手检查已打开的场景。

基本用法

读取对象树

先发送一个只读请求，帮助代理了解你的场景：

显示我的 Roblox 场景的对象树。

代理可以调用 get_object_tree，并概括层级结构中的服务、文件夹、模型、脚本和其他实例。

检查实例

在对象树中找到对象后，可以请求查看其详细信息或属性。条件允许时，请提供精确路径：

检查 Workspace.Map.SpawnLocation 处的实例，并显示其属性。

这类请求可以使用 get_instance 或 get_properties。

创建 Lua 脚本

清楚描述目标位置和所需行为：

在 ServerScriptService 下创建一个 Lua 脚本，在服务器启动时输出启动消息。

助手可以生成 Lua 源代码，并使用 create_script 将其放置在指定的父对象下。在生产项目中依赖生成的代码之前，请先检查代码。

更新现有脚本

要求代理先检查脚本，再说明所需修改：

读取 ServerScriptService.RoundManager 中的脚本，解释其作用，并更新它以添加清晰的调试消息。

代理可以获取脚本，并使用 update_script 替换其源代码。

修改实例属性

指定实例路径、属性和目标值：

将 Workspace.Map.Barrier 的 Transparency 属性修改为 0.5。

此请求对应 set_property。允许修改前请确认目标路径，尤其是在存在名称相似的对象时。

控制试玩

你可以要求已连接的代理启动或停止 Studio 试玩：

启动当前场景的试玩。

停止当前试玩。

这些请求使用 run_playtest 和 stop_playtest。

配置服务器

Roblox Studio MCP 支持用于配置连接和运行时行为的环境变量：

• RBX_MCP_PORT 用于选择 WebSocket 端口，默认值为 44755。
• 将 RBX_MCP_SAFE_MODE 设置为 true 可禁用破坏性操作。
• RBX_MCP_LOG_LEVEL 接受 debug、info、warn 或 error。
• RBX_MCP_TIMEOUT 用于控制请求超时时间，单位为毫秒。

启动 MCP 服务器的进程必须能够访问这些环境变量。定义环境变量的具体方法取决于你的操作系统和 AI 客户端。

高级技巧

先在安全模式下探索

检查不熟悉或重要的场景时，请设置 RBX_MCP_SAFE_MODE=true。安全模式用于只读探索，并会禁用 delete_instance 等破坏性操作。

采用先读后写的工作流程

1. 获取对象树，以发现正确的层级结构。
2. 检查目标实例或脚本。
3. 要求代理解释拟议的更改。
4. 应用一项明确且范围集中的修改。
5. 检查结果，并在适当时运行试玩。

此流程可减少因路径不明确或项目上下文不完整而导致的错误。

提供准确的实例路径

明确指出 Workspace.Map.Door 或 ServerScriptService.RoundManager 等目标的请求更加可靠，而不是只说“门”或“脚本”。如果不知道路径，请先使用 get_object_tree。

使用调试日志排查连接问题

排查发现、连接或超时问题时，请将 RBX_MCP_LOG_LEVEL 设置为 debug。不再需要详细诊断信息后，将其恢复为 info、warn 或 error。

谨慎处理多个 Studio 会话

服务器可以发现多个已打开的 Studio 实例。当有多个会话处于活动状态时，请先使用安全模式进行探索，并在请求编辑前尽可能具体地编写提示词。

为较长操作调整超时时间

如果请求未能在预期时间内完成，请将 RBX_MCP_TIMEOUT 配置为合适的毫秒数。README 未指定默认超时时间，因此请选择适合你环境的值。

安全注意事项

该项目说明，操作在 Studio 插件内的沙箱中执行，不会访问私有数据、操纵内存或执行不受信任的代码。不过，update_script、set_property 和 delete_instance 等 MCP 工具仍可修改你的场景。在确实需要更改之前，请保持安全模式启用，审查生成的 Lua 代码，并为重要工作保留可恢复的版本。

结语

Roblox Studio MCP 为兼容 MCP 的 AI 助手提供了结构化访问 Roblox Studio 的能力。配置好 npx 服务器后，你可以通过 AI 客户端探索对象树、检查属性、编辑 Lua 脚本并管理试玩。请先使用安全模式进行只读检查，在确认路径并审查拟议更改后，再引入范围明确的修改。