连接到 Roblox Studio MCP 服务器 | 文档

Roblox Studio MCP 服务器内置于 Roblox Studio。它实现了模型上下文协议 (MCP)，这是一个开放标准，允许 AI 工具与外部应用程序安全地通信。一旦连接，您的 AI 客户端可以直接与您打开的 Studio 会话进行交互，探索数据模型、编写脚本、运行 Luau 代码并在播放模式中测试您的体验。

本指南向您展示如何将 Studio MCP 服务器连接到流行的 AI 客户端。尽管设置因客户端而异，但核心思想是相同的：您需要配置您的客户端以连接到 MCP 服务器，然后从客户端向您活动的 Studio 会话发送命令。

前提条件

在您能够连接到服务器之前，请确保您已在计算机上安装了最新版本的 Roblox Studio 和首选的 MCP 客户端。

Studio MCP 服务器的工作原理

该服务器作为您计算机上的本地进程运行，并使用 stdio 传输与 AI 客户端进行通信，该传输使用标准输入/输出流。所有操作均通过您的 AI 客户端发起，然后通过此通道发送请求以在您的 Studio 会话中执行操作。

服务器提供以下工具：

脚本
script_read	通过点标记路径从游戏中读取脚本（例如，game.ServerScriptService.MyScript）。支持读取整个脚本或特定行范围。
multi_edit	在一个操作中对脚本应用多个编辑。如果目标路径不存在，则会创建一个新脚本。需要指定 datamodel_type (编辑)。
script_search	通过名称模糊匹配搜索脚本。返回最多 10 个结果。
script_grep	在游戏中的所有脚本中搜索字符串模式。返回最多 50 个匹配项。
资产和内容生成
generate_mesh	根据文本提示使用 AI 生成具有纹理的 3D 网格。
generate_material	生成自定义材质变体。返回基础材质和要应用于部件的材质变体名称。
generate_procedural_model	创建由原始部件（块、球体、圆柱体、楔形体）构建的 3D 物体作为具有可配置属性的 ProceduralModel。支持参考图像和自定义部件模式。
wait_job_finished	等待程序模型生成作业完成并返回最终状态。
search_asset	在 Creator Store（公共市场）和 Creator Inventory（用户、组或宇宙）中搜索资产。支持按资产类型、价格、标签和范围过滤。
insert_asset	通过数字 Roblox 资产 ID 将资产插入游戏。支持模型、网格、图像、音频、视频、动画和包。
upload_image	从 HTTP URL 上传一组图像到 Roblox 资产服务器，返回图像路径至资产 ID 映射。
store_image	从本地文件路径加载图像并返回可传递给其他工具的图像 URI（例如，作为 generate_procedural_model 的参考图像）。
数据模型探索
subagent	启动一个专门的子代理，以自主处理复杂的多步骤任务。可用类型包括 explore（用于代码库调查和游戏状态查询）和 playtest（用于运行游戏场景和验证结果）。
search_game_tree	作为平坦的 JSON 数组探索实例层次结构。支持按路径、实例类型和关键字过滤，具有可配置的深度限制。
inspect_instance	返回有关特定实例的详细信息，包括所有可读属性、自定义属性，以及其子类和后代的摘要。
Luau 执行
execute_luau	在 Studio 中运行 Luau 代码。返回结果或错误。需要指定 datamodel_type（编辑、客户端或服务器）。
游戏测试
get_studio_state	获取 Studio 的当前状态，包括播放状态和可用的数据模型类型。
start_stop_play	开始或停止游戏测试。
get_console_output	检索来自 Studio 输出日志的输出。
screen_capture	捕获当前 Studio 视口并返回图像数据。可选地接受自定义相机位置和观察目标。
玩家输入模拟
character_navigation	将玩家角色移动到给定位置或实例路径。支持可配置的速度倍增器。
user_keyboard_input	按顺序发送一个或多个键盘动作：按下键、抬起键、按键、文本输入或等待。支持针对特定 UI 实例。
user_mouse_input	按顺序发送一个或多个鼠标动作：移动、点击、按钮按下/抬起、滚动或等待。支持针对特定实例或屏幕坐标。
文档和技能
http_get	从允许的 Roblox 文档 URL（引擎 API 参考、创作者文档、云 API、性能优化指南）获取内容。支持在获取的内容中进行关键字搜索。
skill	检索特定技能（例如调试、设备模拟和文档搜索）的详细知识、最佳实践或参考材料。
会话管理
list_roblox_studios	列出所有连接的 Studio 实例，包括它们的名称、ID 和活动状态。这在多个 Studio 窗口打开时非常有用。
set_active_studio	将 Studio 实例设置为活动状态，以便所有后续工具调用都针对该实例。

在 Studio 中启用 MCP 服务器

要在 Studio 中启用 MCP 服务器：

打开助手。
点击 … ⟩ 管理 MCP 服务器。
打开启用 Studio 作为 MCP 服务器。

启用后，设置面板会显示快速连接选项和不同客户端的设置说明。当客户端成功连接时，绿色指示器会显示连接的客户端数量。

连接您的客户端

您可以使用快速连接、JSON 配置或 CLI 命令将客户端连接到 Studio MCP 服务器。

如果您的客户端受支持，请使用快速连接。
如果没有，请使用 JSON 配置，如果您的客户端支持 MCP 配置文件。
否则，请使用 CLI 命令。

Studio MCP 服务器与任何支持 stdio 传输的客户端配合使用。添加配置后，请遵循您的客户端文档完成设置，然后重启客户端以应用更改。

MCP 客户端可以读取和修改您打开的 Roblox 场所中的内容。请确保只连接您信任的客户端。

快速连接

快速连接支持以下客户端：

Antigravity
Codex CLI
Claude Code
Claude Desktop
Cursor
Gemini CLI
Visual Studio Code

要使用快速连接进行连接：

转到助手设置 ⟩ MCP 服务器。
展开快速连接下拉菜单，查看您计算机上已安装的受支持客户端。
开启您选择的客户端。

如果您想要的客户端未出现在快速连接列表中，请安装它并重启 Roblox Studio。

JSON 配置

大多数 MCP 客户端支持 JSON 配置文件。以下示例显示可以使用的完整配置。

如果 Roblox Studio 是您唯一的 MCP 服务器，请按原样使用这些配置。如果您使用多个 MCP 服务器，请复制 Roblox_Studio 条目并将其添加到现有的 mcpServers 字典中。

您的 mcp.json 文件可能已经包含其他条目。当添加 Roblox_Studio 配置时，请确保每个条目之间用逗号分隔。缺失的逗号将导致 JSON 无效，并阻止配置加载。

配置因操作系统而异：

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

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

CLI 命令

某些 MCP 客户端需要 CLI 命令而不是 JSON 配置。使用适合您操作系统的命令：

Windows
cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat

macOS
/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP

使用多个 Studio 实例

您可以将单个 MCP 客户端同时连接到多个正在运行的 Studio 实例。服务器会根据上下文自动确定使用哪个实例（例如，如果您引用特定体验或仅存在于该实例中的对象）。

您可以使用 list_roblox_studios 和 set_active_studio 手动切换实例。

验证您的连接

设置客户端后，请验证连接在 Roblox Studio 中是否正常工作：

打开助手。
点击 … ⟩ 管理 MCP 服务器。
在启用 Studio 作为 MCP 服务器下，检查绿色指示器以确认客户端已成功连接。

故障排除

如果服务器未显示，或工具不可用：

重启 Roblox Studio 和您的 MCP 客户端。
确认命令或二进制路径正确且文件存在。
检查您的 JSON 语法。即使缺少逗号或括号也会导致配置加载失败。