roblox-studio-mcp

Roblox Studio MCP Bridge

一种 模型上下文协议（MCP） 服务，可将 Claude Code 等 AI 编码助手直接连接到 Roblox Studio。可在终端中读取、创建、修改和删除 DataModel 中的实例。

工作原理

Claude Code (MCP Client)
        |
   MCP Server (stdio)
        |
   HTTP Bridge (localhost:3001)
        |
   Studio Plugin (polls every 200ms)
        |
   Roblox Studio DataModel

该桥接分为两部分：

1. MCP 服务端（TypeScript）——在本地运行，通过 MCP 经由 stdio 提供 14 个工具，并在 localhost:3001 提供 HTTP API
2. Studio 插件（Luau）——轮询 HTTP API 获取命令，针对 DataModel 执行命令并返回结果

所有写入操作都通过 ChangeHistoryService 封装，因此可以在 Studio 中使用 Ctrl+Z 撤销每项更改。

可用工具

工具	类型	描述
get_descendants	读取	获取所有后代及其路径，可选 maxDepth
get_children	读取	获取实例的直接子级
get_properties	读取	获取实例的序列化属性
find_instances	读取	按 className 和／或 namePattern 搜索
get_services	读取	列出所有 DataModel 服务
get_selection	读取	获取 Studio 中当前选中的实例
create_instance	写入	使用指定属性创建新 Instance
set_properties	写入	修改现有实例的属性
delete_instance	写入	销毁实例（支持撤销）
clone_instance	写入	将实例克隆到新的父级
move_instance	写入	更改实例的父级
set_selection	写入	设置 Studio 中的选区
insert_service	写入	通过 game:GetService() 插入服务
execute_luau	写入	在插件上下文中执行任意 Luau 代码

路径使用以 game 开头的点号表示法，例如 game.Workspace.SpawnLocation。

前置条件

• Node.js 18+
• Roblox Studio
• Rojo 7+（aftman 或独立安装）

安装

1. 克隆仓库

git clone https://github.com/Justice219/roblox-studio-mcp.git
cd roblox-studio-mcp

2. 安装依赖并构建

npm install
npm run build

也可以直接从 npm 安装：

npm install -g @jamesworkbenchcrm/roblox-studio-mcp

3. 构建并安装 Studio 插件

使用 Rojo：

rojo build plugin.project.json -o MCPBridge.rbxmx

然后将插件文件复制到 Roblox 插件文件夹：

操作系统	路径
macOS	~/Documents/Roblox/Plugins/MCPBridge.rbxmx
Windows	%LOCALAPPDATA%\Roblox\Plugins\MCPBridge.rbxmx

也可以直接构建到插件文件夹：

# macOS
rojo build plugin.project.json -o ~/Documents/Roblox/Plugins/MCPBridge.rbxmx

# Windows
rojo build plugin.project.json -o "%LOCALAPPDATA%\Roblox\Plugins\MCPBridge.rbxmx"

4. 在 Studio 中启用 HttpService

打开 Roblox Studio，然后依次选择：

Home → Game Settings → Security → Allow HTTP Requests → ON

插件需要此设置才能与本地 MCP 服务通信。

5. 配置 MCP 客户端

将服务添加到 MCP 客户端配置中。

Claude Code（~/.claude/settings.json）：

{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["/absolute/path/to/roblox-studio-mcp/dist/index.js"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["/absolute/path/to/roblox-studio-mcp/dist/index.js"]
    }
  }
}

将 /absolute/path/to/ 替换为克隆仓库的实际路径。

6. 重启 Studio 和 MCP 客户端

• 重启 Roblox Studio（或重新加载插件）——工具栏中应会出现“MCP Bridge”按钮
• 重启 Claude Code／MCP 客户端
• 连接成功后，插件状态小组件会显示一个绿色圆点

使用方法

连接后，AI 助手即可直接操作 Studio：

"Create a Part named SpawnPad in Workspace at position 0, 5, 0"
"Get all children of ServerScriptService"
"Find all instances with className RemoteEvent"
"Set the BrickColor of game.Workspace.SpawnPad to Bright green"

助手会使用 MCP 工具读取 DataModel、创建实例、设置属性等，所有更改都会实时反映在 Studio 中，并且完全支持撤销。

配置

环境变量	默认值	描述
MCP_BRIDGE_PORT	3001	HTTP 桥接端口

MCP_BRIDGE_PORT=4000 npm start

开发

# Watch mode — recompiles on file changes
npm run dev

# Type-check without emitting
npm run typecheck

# Build
npm run build

# Start the server
npm start

架构

src/
├── index.ts           # Entry point — wires up all components
├── types.ts           # Interfaces, constants, command type definitions
├── mcp-server.ts      # MCP tool definitions (14 tools with Zod validation)
├── http-bridge.ts     # Express HTTP server (poll/result/heartbeat endpoints)
└── command-queue.ts   # In-memory command queue with timeout management

plugin/
├── init.server.luau   # Plugin entry point — polling loop, UI, toolbar
└── modules/
    ├── CommandRouter.luau  # Dispatches commands to handlers
    ├── HttpClient.luau     # HTTP requests to the bridge
    ├── PathResolver.luau   # Dot-notation path ↔ Instance resolution
    └── Serializer.luau     # Roblox type ↔ JSON serialization

安全

• HTTP 桥接仅绑定到 127.0.0.1——绝不会暴露到网络
• 写入操作通过 ChangeHistoryService 封装，以支持撤销
• 命令在 30 秒后超时
• 连接需要每 10 秒发送一次心跳
• execute_luau 会在插件上下文中执行代码，且没有沙箱保护——仅对可信输入使用

支持的 Roblox 类型

序列化器支持以下类型的双向转换：

Vector3 · Vector2 · CFrame · Color3 · BrickColor · UDim · UDim2 · Rect · NumberSequence · ColorSequence · NumberRange · Enum · Instance · Font · PhysicalProperties · Ray

所有类型都使用 { _type: "TypeName", ... } JSON 格式，以实现无损往返转换。

故障排除

插件显示红点 /“已断开连接”

• 确保 MCP 服务正在运行（npm start）
• 检查 Studio 中是否已启用 HttpService
• 确认端口匹配（默认值为 3001）

Claude Code 中出现“插件未连接”错误

• 打开 Studio，检查 MCP Bridge 工具栏按钮是否已启用
• 插件会在加载时自动启动——尝试重新加载插件
• 检查 Studio 的 Output 窗口是否有错误消息

端口已被占用

• 可能有另一个实例正在运行。结束该实例或使用其他端口：

  MCP_BRIDGE_PORT=4000 npm start
  

npm

npm install -g @jamesworkbenchcrm/roblox-studio-mcp

https://www.npmjs.com/package/@jamesworkbenchcrm/roblox-studio-mcp

许可证

MIT