Roblox Studio

Roblox工作室MCP桥

A. 模型上下文协议（MCP） 连接AI编码助手的服务器，如 克劳德代码 直接 Roblox工作室读取、创建、修改和删除DataModel中的实例——所有这些都可以从您的终端完成。

运作原理

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

这座桥有两半：

1. MCP服务器 （TypeScript）-本地运行，通过stdio上的MCP公开14个工具，并在上提供HTTP API localhost:3001
2. 工作室插件 （Luau）-轮询HTTP API中的命令，根据DataModel执行这些命令，并返回结果

所有写入操作都封装在 ChangeHistoryService，因此每个更改都可以通过以下方式撤消 Ctrl+Z 在工作室。

可用工具

路径使用从开始的点表示法 game例如。 game.Workspace.SpawnLocation.

先决条件

• Node.js 18+
• Roblox工作室
• 红色 7+ (阿夫特曼 或独立安装）

安装

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
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工作室，然后：

Home → 游戏设置→ 安全→ 允许HTTP请求→ ON

这是插件与本地MCP服务器通信所必需的。

5.配置您的MCP客户端

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

克劳德代码 (~/.claude/settings.json):

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

克劳德桌面版 (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桥”按钮
• 重新启动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=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

所有类型都使用a { _type: "TypeName", ... } JSON格式，用于无损往返。

故障排除

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

• 确保MCP服务器正在运行(npm start)
• 检查Studio中是否启用了HttpService
• 验证端口是否匹配（默认值 3001)

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

• 打开Studio并检查MCP桥工具栏按钮是否启用
• 插件在加载时自动启动——尝试重新加载插件
• 检查Studio的输出窗口以查看错误消息

端口已在使用中

• 另一个实例可能正在运行。杀死它或使用其他端口：

  MCP_BRIDGE_PORT=4000 npm start

npm

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

https://www.npmjs.com/package/@jamesworkbenchcrm/roblox工作室mcp

许可证

麻省理工学院