AI导哈

Roblox Studio MCP控制协议

Roblox Studio MCP是一个用于从AI编码工具控制Roblox Studio的协议服务器，提供工作区探索、实例操作、脚本管理等功能。

  • by paralov
  • Luau
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 paralov/roblox-studio-opencode-mcp

使用说明

Roblox工作室MCP

实验。 这是一项正在进行的积极工作。API将发生变化，功能可能会中断，渲染的屏幕截图是块状近似值，而不是像素精确的预览。使用风险自负。欢迎投稿和bug报告。

用于通过AI编码工具控制Roblox Studio的MCP（模型上下文协议）服务器，如 OpenCode。提供工作区探索、实例操作、脚本管理、工具箱集成、播放测试控件和视口渲染。

建筑

OpenCode / Claude ──stdio/MCP──> MCP Server (Node.js) ──HTTP──> Studio Plugin (Lua)
                                  :28821 bridge                  polls for commands

MCP服务器在上运行一个小型HTTP服务器 127.0.0.1:28821Roblox Studio插件每250毫秒轮询一次此服务器上的挂起命令，在Studio中执行这些命令，并将结果发布回来。

设置

1.安装依赖项并构建

npm install
npm run build

2.安装Studio插件

自动：

npm run install-plugin

手册：

复制 plugin/RobloxStudioMCP.server.lua 到您的Roblox Studio插件文件夹：

平台 路径
macOS ~/Documents/Roblox/Plugins/
窗户 %LOCALAPPDATA%\Roblox\Plugins\

3.激活插件

在Studio中，单击 MCP电桥 工具栏中的按钮。将出现一个状态小部件，显示连接状态。

注： 插件HTTP请求不受“允许HTTP请求”游戏设置的限制。该设置仅适用于游戏脚本——插件可以自由地进行HTTP调用。

4.配置OpenCode

包括 opencode.json 从项目根运行OpenCode时有效：

{
  "mcp": {
    "roblox-studio": {
      "type": "local",
      "command": ["node", "dist/index.js"],
      "environment": {
        "ROBLOX_MCP_PORT": "28821"
      }
    }
  },
  "default_agent": "studio"
}

如果你想在其他项目中使用它，请使用绝对路径 dist/index.js 在命令数组中。

工具（6个合并）

所有工具都使用 action 参数以选择特定操作。

roblox_get --只读查询

动作 描述
ping 检查插件连接状态并获取位置信息
tree 实例层次结构的ASCII树视图
search 按名称子字符串和/或类名搜索
instance 获取特定实例的详细信息
properties 读取实例的所有公共属性
descendants_summary 带有后代计数的类细分
selection 获取当前选定的实例
output_log 读取最近的输出窗口条目
texture_info 获取实例和子体的纹理/贴花资源ID

roblox_manage --实例突变

动作 描述
create 创建具有属性的零件、模型、文件夹等
create_multiple 一次批量创建多个实例
update 更新属性（位置、大小、颜色等）
reset_pivot 将模型的WorldPivot重置为边界框中心
delete 销毁实例（可撤消）
clone 使用可选重命名/重解析进行克隆
reparent 将实例移动到新的父级
set_selection 选择特定实例
undo 撤消上次操作
redo 重做上次未执行的操作

roblox_script --脚本CRUD和执行

动作 描述
create 创建脚本/LocalScript/ModuleScript
read 读取脚本源和元数据
update 更新源代码（适用于开放编辑器）
execute 在Studio上下文中执行Lua代码段

roblox_scene --相机和截图

动作 描述
screenshot 渲染当前视口的PNG（几何体+颜色+材质，无纹理）
move_camera 在实例上明确定位相机或自动取景

roblox_toolbox --创作者商店

动作 描述
search 搜索免费型号/贴花/音频
insert 按ID插入工具箱资产
strip_scripts 从插入的模型中删除所有脚本

roblox_playtest --测试会话

动作 描述
start 开始游戏测试会话
stop 停止当前的游戏测试
status 获取当前状态（编辑/运行/播放）
move_camera 在游戏测试期间移动相机
fire_click 点击探测器
fire_proximity 触发邻近提示
get_state 读取游戏状态（玩家、排行榜统计）
execute 在现场游戏环境中运行Lua

实例路径

实例由点分隔的路径引用 game:

Workspace                         -- game.Workspace
Workspace.SpawnLocation           -- a SpawnLocation in Workspace
ServerScriptService.GameScript    -- a script in ServerScriptService
ReplicatedStorage.Modules.Utils   -- nested path

代理

OpenCode代理定义包含在 .opencode/agents/studio.md。它使用Roblox Studio领域知识和工具使用模式配置AI。这 opencode.json 将其设置为默认代理。

环境变量

变量 默认值 描述
ROBLOX_MCP_PORT 28821 HTTP网桥端口

已知限制

  • 截图 是从几何数据渲染的软件，没有纹理、照明或后处理。它们显示的是形状、颜色和空间关系，而不是Studio视口的实际外观。
  • 播放测试控制 用途 RunService:Run()/:Stop() 它适用于服务器端测试，但不能完全复制Play Solo（没有本地玩家角色）。
  • 工具箱搜索 点击公共Roblox API，并可能受到费率限制。
  • 脚本执行 运行通过 require() 在临时ModuleScript上。在此上下文中，某些API可能不可用。
  • 实例路径 使用点分隔的名称，因此实例 . 以他们的名义将无法正确解析。

许可证

麻省理工学院

相关 MCP