python roblox studio MCP

Roblox工作室MCP桥

Roblox Studio插件，通过HTTP将Studio连接到外部MCP（模型上下文协议）服务器，使AI工具能够读取和操纵游戏的层次结构、脚本、属性等。

运行时分为两个进程：

• roblox_bridge_server.py：端口上的单个长期HTTP守护进程 28650 该工作室进行了民意调查。
• roblox_mcp_server.py：一个每个代理的MCP stdio适配器，用于将工具调用转发到网桥。

安装

选项A——安装程序脚本（推荐）

1. 去 发布 页面和下载 install.py （需要Python 3.8+） 或 适用于您平台的独立可执行文件：

- Linux： install-linux - macOS： install-macos *（右键单击→ 首次运行时打开以绕过看门人）* - 窗户： install-windows.exe

1. 运行安装程序——它将引导您完成Claude Desktop、Claude Code、OpenAI Codex或OpenCode的插件放置和MCP服务器注册。

- 高级：通过 --server-script /absolute/path/to/roblox_mcp_server.py （或 --server-path)选择脚本的安装位置；安装程序现在将两者都放置 roblox_mcp_server.py 和兄弟姐妹 roblox_bridge_server.py. - 克劳德桌面高级：通过 --claude-desktop-config /absolute/path/to/claude_desktop_config.json 使用自定义配置位置。

1. 打开Roblox工作室。这 Roblox MCP 工具栏按钮将会出现。
2. 启用 HTTP请求 在 *游戏设置→ 安全* （插件将自动尝试此操作）。
3. 点击 开始桥接轮询 在插件小部件中。

选项B——自动更新程序向导（新）

当您希望在安装之前始终拉取最新的安装程序向导时，请使用此选项。

1. 下载 update.py 从 发布 （需要Python 3.8+）。
2. 运行它：

- Linux/macOS： python3 update.py - 窗户： py update.py （或 python update.py)

1. 更新程序获取最新 install.py 从最新版本开始，启动完整的交互式安装程序，以便您可以选择首选的安装选项。

- 您还可以设置 --server-script /absolute/path/to/roblox_mcp_server.py 运行时 update.py；它在该文件夹中安装适配器+网桥脚本。

您也可以通过更新程序传递安装程序标志：

python3 update.py --server-script /opt/roblox-mcp/roblox_mcp_server.py --claude-desktop-config ~/.config/Claude/claude_desktop_config.json -- --non-interactive --skip-skill --agent codex

选项C——手动插件安装

1. 去 发布 页面和下载 RobloxMcpBridge.rbxm.\

--或--\ 从下载最新的构建工件 行动 （无需发布）。

1. 地方 RobloxMcpBridge.rbxm 在你的Roblox 插件 文件夹：

- 窗户： %LOCALAPPDATA%\Roblox\Plugins\ - macOS： ~/Documents/Roblox/Plugins/ - Linux（Sober/Flatpak）： ~/.var/app/org.vinegarhq.Sober/data/roblox/Plugins/ - Linux（醋/酒）： ~/.var/app/org.vinegarhq.Vinegar/data/prefixes/studio/drive_c/users//AppData/Local/Roblox/Plugins/

1. 打开Roblox工作室。这 Roblox MCP 工具栏按钮将会出现。
2. 启用 HTTP请求 在 *游戏设置→ 安全* （插件将自动尝试此操作）。
3. 启动网桥守护进程一次： python3 /path/to/roblox_bridge_server.py （如果启用了适配器自动启动，则可选）。
4. 点击 开始桥接轮询 在插件小部件中，确认 client_id 文本框值（默认为 PlaceId).

选项D——手动注册MCP服务器

如果你已经安装了插件，请将其添加到你的AI客户端的配置中：

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "python3",
      "args": ["/path/to/roblox_mcp_server.py"]
    }
  }
}

• 克劳德桌面： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）
• 克劳德代码： claude mcp add Roblox_Studio --scope user -- python3 /path/to/roblox_mcp_server.py
• OpenAI Codex： ~/.codex/config.toml
• OpenCode： ~/.config/opencode/mcp.json （CLI注册不可用时回退）

网桥启动模式

您可以在以下任一模式下运行：

1. 自动启动（默认）：如果满足以下条件，每个MCP适配器进程都会尝试启动网桥 http://localhost:28650/status 不可用。
2. 手动电桥：run python3 /path/to/roblox_bridge_server.py 然后启动一个或多个MCP适配器进程 python3 /path/to/roblox_mcp_server.py --no-autostart.

如果网桥不可用且禁用自动启动，适配器将退出并显示： Bridge not running. Start it with: python roblox_bridge_server.py.

多代理使用模式

• 多个工作室同时开放：每个Studio窗口默认值 client_id 到其 PlaceId.使用 studio_get_connection_status / GET /clients 要发现活动客户端，请通过 client_id 在工具调用中以特定位置为目标。
• 多个代理→ 一个地方：将所有代理指向同一位置 client_id （通常是地点id）。作业通过共享网桥队列进行序列化。
• 自定义分组：在插件中键入任何字符串 Client ID 盒子（例如 map-editor 或 scripting)将作业路由到该逻辑Studio目标。

当地建筑（Rojo）

# Install Rojo (https://rojo.space)
rojo build default.project.json --output RobloxMcpBridge.rbxm

这 default.project.json 地图 src/plugin/init.plugin.luau 作为插件根脚本 Tools/ 和 Utils/ 作为子模块脚本——匹配方式 require(script.Tools.*) 在运行时解析。

项目结构

src/plugin/
├── init.plugin.luau         # Entry point: toolbar UI, polling loop, handler dispatch
├── Tools/
│   ├── InstanceTools.luau   # Instance hierarchy: create/delete/clone/reparent/tree/selection
│   ├── PropertyTools.luau   # Properties + attributes get/set
│   ├── TagTools.luau        # CollectionService tags
│   ├── ScriptTools.luau     # Read/write/patch/search/functions/find+replace
│   ├── EditorTools.luau     # ScriptEditorService open/list/close
│   ├── HistoryTools.luau    # Undo/redo/waypoints
│   ├── StudioTools.luau     # Run code, insert model, console output, run mode
│   ├── TerrainTools.luau    # Terrain fill/replace/read/clear tools
│   ├── BulkTools.luau       # Bulk create/set/delete/get-property operations
│   ├── BuildTools.luau      # Export/import instance subtrees as JSON
│   ├── AnalyzeTools.luau    # Analyze scripts / other instances.
│   └── DataModelTools.luau  # Place/workspace/team/lighting metadata tools
└── Utils/
    ├── Types.luau           # Rich type serialization / deserialization
    ├── Instances.luau       # Instance ID map and path resolution helpers
    ├── History.luau         # ChangeHistoryService recording helpers
    ├── Syntax.luau          # Lua syntax validation utilities
    ├── Logger.luau          # Widget log panel helper
    └── PluginUtils.luau     # Shared plugin-side utility helpers

支持的工具

游戏测试技巧

• 使用 roblox_run_script_in_play_mode 用于具有超时和结构化返回有效负载的单次脚本执行。
• 使用 roblox_start_stop_play 用于手动会话(start_play / run_server / stop).
• 确认转换 roblox_get_studio_mode 在发出后续命令之前。
• 流式传输会话日志 roblox_get_playtest_output；使用 roblox_get_console_output 全球产出。
• 如果Studio在运行后卡在Play中，请调用 roblox_start_stop_play 随着 stop，稍等片刻，然后重新检查模式。

添加新工具

1. 在中创建（或编辑）相应的模块 src/plugin/Tools/.
2. 从模块中将处理程序导出为命名函数。
3. 在 handlers 桌子在 init.plugin.luau.