Roblox工作室MCP桥
Roblox Studio插件，通过HTTP将Studio连接到外部MCP（模型上下文协议）服务器，使AI工具能够读取和操纵游戏的层次结构、脚本、属性等。
运行时分为两个进程：
roblox_bridge_server.py：端口上的单个长期HTTP守护进程28650该工作室进行了民意调查。roblox_mcp_server.py：一个每个代理的MCP stdio适配器，用于将工具调用转发到网桥。
安装
选项A——安装程序脚本（推荐）
- 去 发布 页面和下载
install.py（需要Python 3.8+） 或 适用于您平台的独立可执行文件：
- Linux： install-linux - macOS： install-macos *（右键单击→ 首次运行时打开以绕过看门人）* - 窗户： install-windows.exe
- 运行安装程序——它将引导您完成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 使用自定义配置位置。
- 打开Roblox工作室。这 Roblox MCP 工具栏按钮将会出现。
- 启用 HTTP请求 在 *游戏设置→ 安全* （插件将自动尝试此操作）。
- 点击 开始桥接轮询 在插件小部件中。
选项B——自动更新程序向导（新）
当您希望在安装之前始终拉取最新的安装程序向导时，请使用此选项。
- 下载
update.py从 发布 （需要Python 3.8+）。 - 运行它：
- Linux/macOS： python3 update.py - 窗户： py update.py （或 python update.py)
- 更新程序获取最新
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——手动插件安装
- 去 发布 页面和下载
RobloxMcpBridge.rbxm.\
--或--\ 从下载最新的构建工件 行动 （无需发布）。
- 地方
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/
- 打开Roblox工作室。这 Roblox MCP 工具栏按钮将会出现。
- 启用 HTTP请求 在 *游戏设置→ 安全* （插件将自动尝试此操作）。
- 启动网桥守护进程一次：
python3 /path/to/roblox_bridge_server.py（如果启用了适配器自动启动，则可选）。 - 点击 开始桥接轮询 在插件小部件中，确认
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注册不可用时回退）
网桥启动模式
您可以在以下任一模式下运行：
- 自动启动（默认）：如果满足以下条件，每个MCP适配器进程都会尝试启动网桥
http://localhost:28650/status不可用。 - 手动电桥：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支持的工具
| 类别 | 工具 |
|---|---|
| 连接 | studio_get_connection_status, studio_list_connections |
例子 roblox_list_services, roblox_get_children, roblox_get_descendants, roblox_get_instance, roblox_find_instances, roblox_search_by_property, roblox_get_tree, roblox_create_instance, roblox_delete_instance, roblox_clone_instance, roblox_smart_duplicate, roblox_reparent_instance, roblox_set_name, roblox_select_instance, roblox_get_selection | |
| 属性与特性 | roblox_get_properties, roblox_get_all_properties, roblox_get_class_info, roblox_set_properties, roblox_get_attributes, roblox_set_attributes |
| 标签 | roblox_get_tags, roblox_add_tag, roblox_remove_tag |
| 脚本 | roblox_read_script, roblox_write_script, roblox_patch_script, roblox_get_script_lines, roblox_search_script, roblox_get_script_functions, roblox_search_across_scripts, roblox_find_and_replace_in_scripts |
| 编辑 | roblox_open_script, roblox_get_open_scripts, roblox_close_script |
| 历史 | roblox_undo, roblox_redo, roblox_set_waypoint |
| 工作室 | roblox_run_code, roblox_insert_model, roblox_get_console_output, roblox_get_playtest_output, roblox_start_stop_play, roblox_get_studio_mode, roblox_run_script_in_play_mode |
| 地形 | roblox_terrain_fill_block, roblox_terrain_fill_ball, roblox_terrain_fill_cylinder, roblox_terrain_replace_material, roblox_terrain_read_voxels, roblox_terrain_clear_region |
| 散装 | roblox_bulk_create_instances, roblox_bulk_set_properties, roblox_bulk_delete_instances, roblox_bulk_get_properties |
| 数据模型 | roblox_get_place_info, roblox_set_lighting, roblox_get_workspace_info, roblox_get_team_list, roblox_get_lighting_effects |
| 构建 | roblox_export_build, roblox_import_build |
| 分析 | roblox_analyze_script |
游戏测试技巧
- 使用
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，稍等片刻，然后重新检查模式。
添加新工具
- 在中创建（或编辑）相应的模块
src/plugin/Tools/. - 从模块中将处理程序导出为命名函数。
- 在
handlers桌子在init.plugin.luau.