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"))()

📚 详细文档

工具列表

主/辅模式

默认情况下，服务器在端口 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"
      ]
    }
  }
}

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

🔧 技术细节

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

📄 许可证

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

⚠️ 重要提示

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