roblox-executor-mcp

🚀 Roblox执行器MCP服务器

这是一个MCP服务器，用于连接大语言模型（LLMs）和运行中的Roblox游戏客户端。借助它，你可以执行代码、检查脚本、监控远程调用等。

🚀 快速开始

pnpm install && pnpm run build

添加到你的AI客户端

• Cursor：设置 > 功能 > MCP > 添加：名称为 roblox-executor-mcp，类型为 command，命令为 node /path/to/MCPServer/dist/index.js。
• Claude Desktop / Antigravity：在你的JSON配置中添加以下内容：

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

• Codex：设置 > MCP设置 > 添加服务器：名称为 roblox-executor-mcp，类型为 STDIO，命令为 node，参数为 /path/to/MCPServer/dist/index.js。

从Roblox进行连接

在你的执行器中运行 connector.luau，或者使用快速加载器：

-- getgenv().BridgeURL = "10.0.0.4:16384" (默认为localhost，如有需要可更改)
-- getgenv().DisableWebSocket = true
-- getgenv().DisableInitialScriptDecompMapping = true (在运行与脚本相关的工具之前禁用脚本反编译)
loadstring(game:HttpGet("https://raw.githubusercontent.com/notpoiu/roblox-executor-mcp/refs/heads/main/connector.luau"))()

✨ 主要特性

• 代码执行与数据查询：运行Lua代码并从游戏客户端获取数据。
• 脚本检查：反编译LocalScripts/ModuleScripts并在源代码中进行搜索。
• 实例搜索：通过 QueryDescendants 和层次树使用类似CSS的选择器。
• 远程监控：集成 Cobalt 来拦截、记录、阻止和忽略远程调用/可绑定对象。
• 多客户端支持：同时连接多个Roblox客户端；通过 clientId 定位每个客户端。可在 http://localhost:16384/ 访问仪表盘。
• 截图功能：捕获Roblox窗口的截图（仅适用于Windows）；作为辅助服务器运行时，截图会转发到主服务器。
• 主/辅模式：多个MCP实例自动协调；辅助服务器通过主服务器进行转发，并在主服务器断开连接时自动升级为主服务器。支持通过 --baseurl 连接远程主服务器。

📦 安装指南

• 一个支持 loadstring、request 以及（最好）WebSocket 的Roblox执行器。
• Node.js ≥ 18。

💻 使用示例

基础用法

在执行器中运行 connector.luau 或使用快速加载器的代码示例：

-- getgenv().BridgeURL = "10.0.0.4:16384" (默认为localhost，如有需要可更改)
-- getgenv().DisableWebSocket = true
-- getgenv().DisableInitialScriptDecompMapping = true (在运行与脚本相关的工具之前禁用脚本反编译)
loadstring(game:HttpGet("https://raw.githubusercontent.com/notpoiu/roblox-executor-mcp/refs/heads/main/connector.luau"))()

📚 详细文档

工具列表

| 类别 | 工具 | 描述 | |------|------|------| | 执行 | execute | 运行Lua代码（操作） | | | execute-file | 运行本地的 .luau/.lua 文件 | | | get-data-by-code | 运行Lua代码并返回结果 | | 脚本 | get-script-content | 反编译脚本的源代码 | | | search-scripts-sources | 根据源代码内容搜索所有脚本 | | 内省 | list-clients | 列出已连接的客户端 | | | get-console-output | 获取控制台日志 | | | search-instances | 类似CSS的实例搜索 | | | get-descendants-tree | 实例层次树 | | | get-game-info | 游戏元数据 | | 远程监控 | ensure-remote-spy | 加载Cobalt（首次使用需要） | | | get-remote-spy-logs | 获取捕获的远程调用日志 | | | clear-remote-spy-logs | 清除所有日志 | | | block-remote | 阻止/取消阻止远程调用 | | | ignore-remote | 忽略/取消忽略远程调用 | | 截图 | list-roblox-windows | 列出可见的Roblox窗口及其PID | | | screenshot-window | 通过PID捕获Roblox窗口（仅适用于Windows） | | GUI交互 | click-button | 模拟在Textbutton/ImageButtton上的按钮点击 | | | type-text-box | 与文本框进行交互 |

主/辅模式

默认情况下，服务器在端口 16384 上以 主服务器 模式启动。如果该端口已被占用，它将自动成为 辅助服务器，将所有工具调用转发到主服务器。当主服务器断开连接时，辅助服务器会自动升级为主服务器。

远程主服务器 (--baseurl)

将此实例作为辅助服务器连接到 远程 主服务器 —— 当你的AI客户端运行在macOS/Linux上，而Roblox运行在Windows机器上时，这非常有用：

{
  "mcpServers": {
    "roblox-executor-mcp": {
      "command": "node",
      "args": [
        "/path/to/MCPServer/dist/index.js",
        "--baseurl",
        "http://<primary-host>:16384"
      ]
    }
  }
}

| 场景 | 结果 | |------|------| | --baseurl 已设置，远程服务器可达 | 作为辅助服务器将调用转发到该主机 | | --baseurl 已设置，远程服务器 不可达 | 回退到在本地以主服务器模式启动 | | --baseurl 已设置，远程服务器不可达 且 本地端口被占用 | 成为本地主服务器的辅助服务器 | | 未设置 --baseurl | 默认：以主服务器模式启动，或者如果端口已被使用，则以本地辅助服务器模式启动 |

注意：screenshot-window 和 list-roblox-windows 会通过HTTP转发到主服务器，因此Mac辅助服务器可以捕获运行在Windows主服务器上的窗口截图。

🔧 技术细节

该MCP服务器通过连接大语言模型和Roblox游戏客户端，实现了一系列功能。它利用Node.js作为服务端，支持多种工具和操作。在主/辅模式下，多个实例可以自动协调，确保服务的稳定性和可用性。同时，通过集成Cobalt，实现了对远程调用的监控和管理。

📄 许可证

文档中未提及相关许可证信息。

⚠️ 重要提示

• 任意代码执行：仅与受信任的大语言模型一起使用；任何连接的AI客户端都可以在你的Roblox会话中运行代码。
• 不要将HTTP服务器暴露到互联网。端口 16384 未经过身份验证。任何能够访问该端口的人都可以在你的游戏中执行代码、截取屏幕截图并读取客户端数据。如果你需要跨机器访问（例如使用 --baseurl），请使用 本地网络 / VPN 或 SSH隧道 —— 切勿通过公共路由器或云防火墙转发该端口。