Roblox MCP桥
通过模型上下文协议（MCP）将AI助手连接到Roblox Studio的网桥服务器。这允许像Claude或其他LLM驱动的编码助手这样的AI工具实时读取和修改您的Roblox游戏数据。
运行python文件并在此处安装插件：https://create.roblox.com/store/asset/136954959051709/RobloxBridgePlugin
这有什么作用？
该项目在您的AI助手和Roblox Studio之间创建了一个双向沟通渠道。一旦连接，您的AI可以：
- 浏览游戏的对象层次结构
- 读取和修改脚本源代码
- 搜索特定脚本或对象
- 创建新实例（零件、文件夹、脚本等）
- 删除对象并修改其属性
- 浏览Workspace、ReplicatedStorage和ServerScriptService等服务
可以把它看作是让你的AI助手直接进入Roblox Studio，这样它就可以帮助你调试、重构或构建功能，而无需你来回手动复制粘贴代码。
建筑
这座桥由两个主要部分组成：
Python服务器 (roblox_mcp_server.py)
- 运行Roblox插件连接到的websocket服务器
- 展示人工智能助手可以调用的MCP工具
- 处理请求路由和超时管理
- 支持多种传输协议（stdio、SSE、可流式传输http）
Roblox插件 (RobloxBridgePlugin.lua)
- 作为插件在Roblox Studio中运行
- 通过websocket连接到Python服务器
- 对实时数据模型执行命令
- 如果连接中断，则自动重新连接
设置
需求
- Python 3.10或更新版本
- Roblox工作室
- 以下Python包：
- mcp （快速MCP） - websockets
安装
- 安装Python依赖项：
pip install mcp websockets- 安装Roblox插件：
- 打开Roblox工作室 - 打开插件文件夹（文件>打开>插件文件夹，或 %LOCALAPPDATA%\Roblox\Plugins 在Windows上） - 复制 RobloxBridgePlugin.lua 进入插件文件夹 - 如果需要，请重新启动Roblox Studio
- 启动网桥服务器：
python roblox_mcp_server.py服务器将启动两个侦听器：
- 上的Websocket桥
ws://127.0.0.1:9090（Roblox工作室） - MCP HTTP端点已打开
http://127.0.0.1:8000（适用于AI助手）
- Studio启动时，Roblox插件应自动连接。在输出窗口中查找连接消息。
配置
您可以使用环境变量自定义网桥行为：
# Websocket settings
export ROBLOX_BRIDGE_HOST=127.0.0.1
export ROBLOX_BRIDGE_PORT=9090
export ROBLOX_BRIDGE_TIMEOUT=12
# MCP server settings
export MCP_HTTP_HOST=127.0.0.1
export MCP_HTTP_PORT=8000
export MCP_TRANSPORT=streamable-http
# Logging
export ROBLOX_BRIDGE_LOG=DEBUG您还可以将传输模式作为命令行参数传递：
python roblox_mcp_server.py --transport stdio
python roblox_mcp_server.py --transport sse --mount-path /mcp可用操作
读取操作
- wait_for_roblox：等待Roblox插件连接
- 列表_儿童：获取游戏层次结构中任何对象的直接子对象
- read_script：从脚本、本地脚本或模块脚本获取源代码
- search_for_string：在游戏中的所有脚本中搜索特定字符串
- 搜索对象：按名称查找对象（模糊搜索，不区分大小写）
写入操作
- write_script：覆盖脚本的源代码
- 创建实例：创建新对象（零件、文件夹、脚本等）
- 删除实例：永久删除一个对象及其所有子对象
- set_属性：修改名称、位置、颜色等属性。
所有写入操作在Roblox Studio中立即生效，您可以使用Ctrl+Z撤消它们。
路径格式
Roblox中的对象使用斜线分隔的路径引用：
game/Workspace/Part
game/ReplicatedStorage/RemoteEvents/PlayerJoined
game/ServerScriptService/GameManager插件会自动解析服务，因此 game/Workspace 将正确找到工作区服务，即使从技术上讲它是 game.
用法示例
一旦一切正常运行，你的AI助手就可以与你的Roblox游戏进行交互。例如：
“查找所有引用'PlayerAdded'的脚本，并向我显示代码”
AI将：
- 呼叫
search_for_string带有“PlayerAdd” - 呼叫
read_script对于每个结果 - 显示相关代码
或者：“在ReplicatedStorage中创建一个名为'Config'的新ModuleScript”
AI将：
- 呼叫
create_instanceclassName=“ModuleScript”，parentPath=“game/ReplicatedStorage”，name=“Config” - 确认实例已创建
故障排除
插件未连接：
- 确保Python服务器首先运行
- 检查端口9090是否未被防火墙阻止
- 在Roblox Studio的输出窗口中查找错误消息
- 尝试单击插件工具栏中的“ReconnectMCPBridge”按钮
超时错误：
- 增加超时时间
ROBLOX_BRIDGE_TIMEOUT=30 - 大型搜索操作可能需要比默认的12秒更长的时间
权限错误：
- 确保Roblox Studio有访问网络资源的权限
- 某些公司网络可能会阻止websocket连接
写入操作不起作用：
- 检查您是否未处于播放模式（写入操作仅在编辑模式下有效）
- 验证路径是否存在且正确
安全说明
此网桥在您的计算机上本地运行，默认情况下只接受来自localhost的连接。Roblox插件只能与当前打开的Studio会话交互。
如果你需要在网络上暴露网桥，你可以更改主机设置，但要注意，这会让任何可以访问该端口的人都可以完全读/写你的Roblox游戏。
延伸大桥
这座桥的设计是可扩展的。要添加新操作，请执行以下操作：
- 在中添加新的命令处理程序
RobloxBridgePlugin.lua到CommandHandlers桌子 - 将相应的方法添加到
RobloxBridge上课中roblox_mcp_server.py - 将其作为MCP工具使用
@mcp_app.tool()装饰器
该插件支持常见Roblox数据类型（如Vector3、Color3和UDim2）的类型转换，因此您可以从Python端将它们作为JSON对象传递。
许可证
本项目按原样提供，用于教育和发展目的。