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隧道 —— 切勿通過公共路由器或雲防火牆轉發該端口。