Skip to content

TonyD365/Roickbot

BranchesTags

Repository files navigation

Roickbot

CI Latest release Downloads total Downloads latest Stars Last commit License: MIT

A desktop app + MCP server that lets Claude Code — and any other MCP client (Gemini, Cursor, VS Code, …) — control Roblox Studio. Your AI can read and edit scripts, inspect and modify the scene and models, run the simulation, and — in later phases — build graphics and drive an in-game Bot that reports what it "sees" as structured data, all through natural language from your editor.

Status: v1.0.0 released. Phase 1 (core) and Phase 2 (make-graphics) are complete — a working, secured bridge with tools for scripts, instances, properties, selection, run/test, and building scenes (parts, terrain, lighting, decals, models, GUI), plus a universal run_luau escape hatch. Phase 3 (Bot vision) is next. Cross-platform installers with auto-update are published on the Releases page.

(中文版见下方 / Chinese version below.)

Table of contents

Features

  • Edit anything in Studio — create / delete / clone / reparent instances, read and write any property, and edit script source via ScriptEditorService.
  • Inspect the scene — walk the DataModel tree, lazily expand large places, and pull detailed, structured views of specific elements (Parts, Scripts, …).
  • Run & test — start / stop / pause the physics simulation (RunService) and query the run state.
  • Universal escape hatch — run_luau executes arbitrary Luau in Studio for anything the typed tools don't cover; effects are undoable.
  • Safe by design — every change is a single undo waypoint, destructive ops require a dry-run preview + confirmation (Claude-facing, no user pop-ups), and Core services are never mutable.
  • Secure local bridge — loopback-only, random per-session Bearer token, Host/Origin validation, and a required custom header to defend against malicious web pages.
  • One-click setup — a desktop app starts the service, shows the pairing token, installs the plugin, and writes the Claude Code MCP config for you.
  • Works with any MCP client — not just Claude: Gemini, Cursor, VS Code/Copilot, Cline, etc. (incl. free options). See docs/CLIENTS.md.
  • Cross-platform releases — CI packages installers: a macOS Universal app (Intel + Apple Silicon) and a Windows x64 installer (runs on Intel and ARM).

How it works

Claude Code (VSCode)
   │  MCP over local HTTP/SSE  (127.0.0.1, Bearer token)
   ▼
Desktop app (Electron)
   ├─ MCP server  (@modelcontextprotocol/sdk, Streamable HTTP)
   ├─ Studio bridge (127.0.0.1, WebSocket)
   └─ token / pairing / auth
   ▲  WebSocket /ws  (persistent, bidirectional)
   ▼
Roblox Studio plugin (Luau)  — runs commands on the DataModel

The Studio plugin connects to the bridge over a WebSocket (Studio's HttpService:CreateWebStreamClient), a persistent two-way channel: the server pushes commands instantly and the plugin streams back results and events — so there's no polling gap, and a dropped connection is detected immediately. The desktop app owns the service lifecycle, hosts both the MCP endpoint (for Claude Code) and the bridge (for the plugin), and helps you connect everything. Because Luau also cannot read real screen pixels, "vision" (Phase 3) is delivered as structured data (raycast hits + nearby objects), not images.

See docs/PROTOCOL.md for the full wire protocol.

Repository layout

Path What
packages/core MCP server + HTTP bridge + security + command queue (TypeScript)
packages/desktop Electron desktop app (start/stop service, pairing, install helpers)
plugin Roblox Studio plugin (Luau, built with Rojo)
docs Install, protocol, tools, security
smoke.mjs End-to-end bridge smoke test (no Studio required)

Installation (end user)

  1. Install the desktop app from the Releases page — a macOS .dmg (Universal: Intel + Apple Silicon) or a Windows .exe (x64, runs on Intel and ARM).
  2. Start the service in the app, pick your client from the dropdown (Codex, Claude Code, Cursor, Gemini CLI, Cline, VS Code) and click Install MCP config — the app writes the roickbot server in that client's exact format and location for you. Then restart the client.
  3. Install the plugin: if it shows offline, click Install plugin and save Roickbot.rbxmx into your Studio Plugins folder.
  4. Enable HTTP in Studio's Command Bar (once per place): game:GetService("HttpService").HttpEnabled = true
  5. Pair: copy the token from the app, paste it into the Roickbot plugin panel in Studio, and click Connect.
  6. Verify: ask Claude to call the health tool — it should report pluginConnected: true.

Full steps: docs/INSTALL.md.

Development

npm install
npm run build:core
npm test                 # unit tests
node smoke.mjs           # end-to-end bridge smoke test (no Studio needed)

To run the desktop app from source you also need the Electron binary (run npm install without ELECTRON_SKIP_BINARY_DOWNLOAD) and a built plugin:

npm run build:plugin     # requires Rojo (see plugin/aftman.toml) -> dist/Roickbot.rbxmx
npm run build:desktop
npm start --workspace packages/desktop

Available tools

Phase 1 (core): health, get_tree, get_children, view_elements, get_properties, set_properties, create_instance, delete_instance, clone_instance, reparent_instance, get_script_source, set_script_source, get_selection, set_selection.

Run / test: start_test, stop_test, pause_test, get_run_state, get_console_output.

Phase 2 (make-graphics): build_parts, set_appearance, edit_terrain, set_lighting, insert_decal, insert_model, build_gui.

Assets & selection: toolbox_search (search Roblox free Models/Decals in-Studio; each result flags hasScripts + parts/classes/size so you can avoid unsafe scripts before inserting), inspect_asset (safety-check one asset off-scene), view_selection (what the user has selected, with details).

Phase 3 (Bot vision & self-test): bot_spawn (with asPlayer to tag it for player-based systems), bot_despawn, bot_move, bot_look, bot_state, bot_see. While a test is running, project-editing tools are locked (RUNTIME_LOCKED) — the run phase is read-only; reads, bot_*, run_luau, fire_signal and get_console_output stay available.

Runtime server agent & events: start_test injects a server-context agent into the running game, so run_luau gains context:"server" (real IsServer()/IsRunning()), fire_signal can trigger server-side listeners (RemoteEvent/BindableEvent/ProximityPrompt/network ownership), and wait_for_event blocks until the test's state changes instead of polling.

Search, tags & surgical edits: edit_script_lines (line-range edits), find_instances, search_by_property, search_scripts (grep all script source) and get_script_info (inspect a script "file" — class/lines/Disabled/RunContext/attributes), plus get_tagged / get_tags / add_tag / remove_tag. search_scripts and get_script_info are read-only, so they work while the game is running — built for debugging a live play-test.

Project harness (cross-session memory): harness_init, harness_session_start, harness_session_end, harness_status, harness_feature_update — a persistent project memory (metadata + features + session handoffs) handled locally by the app, so the AI remembers the project across sessions even with Studio offline.

Universal: run_luau.

All mutating tools accept dryRun: true to preview without applying. Read results are capped for responsiveness — inspect large projects incrementally with maxDepth, maxNodes, limit, and pagination rather than requesting the whole DataModel at once. Full reference: docs/TOOLS.md.

Use with other AI clients

It's a standard MCP server, so it works with any client that supports remote (HTTP) MCP servers with custom headers — not just Claude. Point the client at http://127.0.0.1:7331/mcp with the Authorization: Bearer <token> and X-Roblox-MCP: 1 headers (the token is shown in the app).

No manual editing needed: pick your client (Codex, Claude Code, Cursor, Gemini CLI, Cline, VS Code) in the app's dropdown and click Install MCP config — it writes the right type/key/path for that client automatically (each one differs slightly, e.g. Cline needs streamableHttp, Gemini uses httpUrl).

Google Gemini (free tier) — add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "roickbot": {
      "httpUrl": "http://127.0.0.1:7331/mcp",
      "headers": { "Authorization": "Bearer PASTE_TOKEN", "X-Roblox-MCP": "1" }
    }
  }
}

Cursor, VS Code/Copilot, Cline + local Ollama (free), and other clients are covered — including free model options — in docs/CLIENTS.md.

Security

The bridge runs on your machine, so any web page you open could try to reach 127.0.0.1. The bridge defends against this with several independent checks on every request:

  • Loopback only — binds 127.0.0.1, never 0.0.0.0.
  • Random Bearer token — 256-bit, shown only in the native app, compared in constant time.
  • Studio-side pairing — you paste the token into the plugin; a web page can never obtain it.
  • Host validation — blocks DNS-rebinding.
  • Origin rejection — any request with a browser Origin is refused.
  • Required custom header — X-Roblox-MCP: 1, with no permissive CORS.

Details and threat model: docs/SECURITY.md.

"Think before acting" (三思而后行)

Separately from authentication, the tools are designed so Claude is careful — and without interrupting you. Destructive operations first return a dry-run preview and a one-time confirm token (Claude re-calls to apply); every applied change is a single undo waypoint you can Ctrl+Z; and Core services (CoreGui, CorePackages, …) can never be mutated.

Roadmap

  • Phase 1 — core ✅ scripts, instances, properties, selection, run/test, run_luau.
  • Phase 2 — make-graphics ✅ build_parts, set_appearance, edit_terrain, set_lighting, insert_decal, insert_model, build_gui.
  • Phase 3 — Bot vision & self-test loop ✅ bot_spawn/despawn/move/look/state, bot_see (structured, raycast-based perception); start_test/stop_test/pause_test; a runtime lock that makes the project read-only while the game is running.

License

MIT



Roickbot（中文）

CI Latest release Downloads total Downloads latest Stars Last commit License: MIT

一个桌面应用 + MCP 服务器，让 Claude Code —— 以及任何其它 MCP 客户端（Gemini、Cursor、VS Code…） 直接操控 Roblox Studio。你的 AI 可以读写脚本、 查看和修改场景与模型、运行仿真，并在后续阶段构建图形、驱动一个游戏内 Bot 并以结构化数据的形式"看到" 世界 —— 全程在你的编辑器里用自然语言完成。

状态： v1.0.0 已发布。第一阶段（核心）与第二阶段（做图）均已完成 —— 一条可用且带安全鉴权的桥， 涵盖脚本、实例、属性、选择、运行/测试，以及搭建场景（Part、地形、光照、贴图、模型、GUI），外加万能的 run_luau 逃生舱。第三阶段（Bot 视觉）进行中。带自动更新的跨平台安装包见 Releases 页面。

目录

功能特性

  • 在 Studio 里做任何修改 —— 创建/删除/克隆/移动实例，读写任意属性，通过 ScriptEditorService 编辑脚本源码。
  • 查看场景 —— 遍历 DataModel 树，对大型工程按需懒展开，并拉取特定元素（Part、Script…）的详细结构化信息。
  • 运行与测试 —— 启动/停止/暂停物理仿真（RunService），查询运行状态。
  • 万能逃生舱 —— run_luau 在 Studio 里执行任意 Luau，覆盖封装工具未涉及的一切；效果可撤销。
  • 设计上安全 —— 每次更改都是一个可撤销的 waypoint；破坏性操作需先 dry-run 预览 + 确认（面向 Claude， 不弹用户）；Core 服务永不可改。
  • 安全的本地桥 —— 只绑回环、每会话随机 Bearer token、Host/Origin 校验、必需自定义头，防御恶意网页。
  • 一键配置 —— 桌面应用负责启动服务、显示配对 token、安装插件，并为你写入 Claude Code 的 MCP 配置。
  • 兼容任意 MCP 客户端 —— 不止 Claude：Gemini、Cursor、VS Code/Copilot、Cline 等（含免费方案）， 见 docs/CLIENTS.md。
  • 跨平台发布 —— CI 打包 macOS Universal（Intel + Apple Silicon 通用）与 Windows x64 安装包（Intel/ARM 都能跑）。

工作原理

Claude Code (VSCode)
   │  通过本地 HTTP/SSE 的 MCP  (127.0.0.1, Bearer token)
   ▼
桌面应用 (Electron)
   ├─ MCP 服务器  (@modelcontextprotocol/sdk, Streamable HTTP)
   ├─ Studio 桥 (127.0.0.1, WebSocket)
   └─ token / 配对 / 鉴权
   ▲  WebSocket /ws  (常驻双向连接)
   ▼
Roblox Studio 插件 (Luau)  —— 在 DataModel 上执行命令

Studio 插件通过 WebSocket（Studio 的 HttpService:CreateWebStreamClient）连接到桥 —— 这是一条常驻双向 通道：服务器即时推送命令、插件回传结果与事件，因此没有轮询间隙，连接断开也能立刻感知。桌面应用持有服务的 生命周期，同时托管 MCP 端点（给 Claude Code）和桥（给插件），并帮你把各端连起来。由于 Luau 也读不到真实屏幕 像素，所以"视觉"（第三阶段）以结构化数据（射线命中 + 邻近物体）而非图片的形式提供。

完整通信协议见 docs/PROTOCOL.md。

仓库结构

路径 内容
packages/core MCP 服务器 + HTTP 桥 + 安全 + 命令队列（TypeScript）
packages/desktop Electron 桌面应用（启停服务、配对、安装助手）
plugin Roblox Studio 插件（Luau，用 Rojo 构建）
docs 安装、协议、工具、安全
smoke.mjs 端到端桥烟雾测试（无需 Studio）

安装（最终用户）

  1. 从 Releases 页面下载桌面应用 （Windows .exe 或 macOS .dmg，arm64 / x64）。
  2. 在应用里启动服务，从下拉框选择你的客户端（Codex、Claude Code、Cursor、Gemini CLI、Cline、VS Code） 再点 Install MCP config —— 应用会按该客户端正确的格式与路径自动写入 roickbot 服务， 然后重启对应客户端。
  3. 安装插件：若显示离线，点 Install plugin，把 Roickbot.rbxmx 保存到 Studio 的 Plugins 目录。
  4. 在 Studio 命令栏启用 HTTP（每个 place 一次）： game:GetService("HttpService").HttpEnabled = true
  5. 配对：从应用复制 token，粘贴进 Studio 里的 Roickbot 插件面板，点 Connect。
  6. 验证：让 Claude 调用 health 工具 —— 应返回 pluginConnected: true。

完整步骤见 docs/INSTALL.md。

开发

npm install
npm run build:core
npm test                 # 单元测试
node smoke.mjs           # 端到端桥烟雾测试（无需 Studio）

若要从源码运行桌面应用，还需 Electron 二进制（运行 npm install 时不要设置 ELECTRON_SKIP_BINARY_DOWNLOAD）以及构建好的插件：

npm run build:plugin     # 需要 Rojo（见 plugin/aftman.toml） -> dist/Roickbot.rbxmx
npm run build:desktop
npm start --workspace packages/desktop

可用工具

第一阶段（核心）： health、get_tree、get_children、view_elements、get_properties、 set_properties、create_instance、delete_instance、clone_instance、reparent_instance、 get_script_source、set_script_source、get_selection、set_selection。

运行 / 测试： start_test、stop_test、pause_test、get_run_state、get_console_output。

第二阶段（做图）： build_parts、set_appearance、edit_terrain、set_lighting、 insert_decal、insert_model、build_gui。

素材与选择： toolbox_search（在 Studio 内搜索免费模型/贴图，每条结果标注 hasScripts + 零件/类名/大小， 方便插入前避开带脚本的资源）、inspect_asset（离场体检单个资源）、view_selection（查看用户当前选中的元素及详情）。

第三阶段（Bot 视觉 + 自我测试）： bot_spawn（asPlayer 可打标签给基于玩家的系统用）、 bot_despawn、bot_move、bot_look、bot_state、bot_see。游戏运行时,工程编辑类工具被锁 (RUNTIME_LOCKED)——运行态只读;读取、bot_*、run_luau、fire_signal、get_console_output 仍可用。

运行时 server agent + 事件： start_test 会往运行中的游戏注入一个 server 上下文的 agent，于是 run_luau 多了 context:"server"（真实的 IsServer()/IsRunning()）、fire_signal 能触发服务器端监听 （RemoteEvent/BindableEvent/ProximityPrompt/网络所有权），wait_for_event 则可阻塞等测试状态变化而不用轮询。

搜索 / 标签 / 行级编辑： edit_script_lines（按行区间改脚本）、find_instances、 search_by_property、search_scripts（grep 所有脚本源码）、get_script_info（查看脚本"文件"属性—— 类名/行数/Disabled/RunContext/属性），以及 get_tagged / get_tags / add_tag / remove_tag。 其中 search_scripts 与 get_script_info 是只读的，游戏运行时也能用 —— 专为调试运行中的测试而设。

项目 harness（跨 session 记忆）： harness_init、harness_session_start、harness_session_end、 harness_status、harness_feature_update —— 由应用本地维护的项目记忆（元信息 + features + session 交接）， 让 AI 跨 session 记住项目进度，即使 Studio 没连也能用。

万能： run_luau。

所有变更类工具都支持 dryRun: true 以仅预览不落地。读取结果有安全上限，避免大型工程卡住 Studio；使用 maxDepth、maxNodes、limit 和分页逐步读取，再配合 get_children / view_elements 的筛选来控制返回量。完整参考见 docs/TOOLS.md。

用在其它 AI 客户端

它是标准 MCP 服务器，不止 Claude —— 任何支持"远程(HTTP) MCP + 自定义请求头"的客户端都能用。把客户端 指向 http://127.0.0.1:7331/mcp，带上 Authorization: Bearer <token> 和 X-Roblox-MCP: 1（token 在 App 里）。

无需手动改配置： 在 App 下拉框选好客户端（Codex / Claude Code / Cursor / Gemini CLI / Cline / VS Code）再点 Install MCP config，应用会按各客户端正确的 type/键/路径自动写好（每个略有不同，例如 Cline 必须 streamableHttp、Gemini 用 httpUrl）。

Google Gemini（免费额度） —— 加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "roickbot": {
      "httpUrl": "http://127.0.0.1:7331/mcp",
      "headers": { "Authorization": "Bearer 粘贴你的token", "X-Roblox-MCP": "1" }
    }
  }
}

Cursor、VS Code/Copilot、Cline + 本地 Ollama（免费）等客户端及免费模型选项，详见 docs/CLIENTS.md。

安全

桥运行在你的机器上，因此任何你打开的网页都可能尝试访问 127.0.0.1。桥对每个请求做多重独立校验来防御：

  • 只绑回环 —— 绑定 127.0.0.1，绝不 0.0.0.0。
  • 随机 Bearer token —— 256 位，仅显示在原生应用中，常量时间比较。
  • Studio 端配对 —— 你把 token 粘贴进插件；网页永远拿不到它。
  • Host 校验 —— 阻止 DNS-rebinding。
  • 拒绝 Origin —— 任何带浏览器 Origin 的请求都被拒。
  • 必需自定义头 —— X-Roblox-MCP: 1，且不开放宽松 CORS。

细节与威胁模型见 docs/SECURITY.md。

三思而后行

除了鉴权之外，工具本身的设计也让 Claude 保持谨慎，且不打扰你。破坏性操作会先返回 dry-run 预览和一次性 确认 token（Claude 再次调用才真正执行）；每次落地的更改都是一个可 Ctrl+Z 撤销的 waypoint；Core 服务 （CoreGui、CorePackages…）永远不可改。

路线图

  • 第一阶段 —— 核心 ✅ 脚本、实例、属性、选择、运行/测试、run_luau。
  • 第二阶段 —— 做图 ✅ build_parts、set_appearance、edit_terrain、set_lighting、 insert_decal、insert_model、build_gui。
  • 第三阶段 —— Bot 视觉 + 自我测试闭环 ✅ bot_spawn/despawn/move/look/state、bot_see（基于射线的结构化感知）；start_test/stop_test/pause_test；运行时锁（运行中工程只读）。

许可

MIT

About

A tool that can connect your Roblox Studio with Claude Code or any AI Agents that can use MCP Tools.

Resources

Readme

License

MIT license

Security policy

Security policy
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 27

Public Release v1.4.7 Latest
Jul 18, 2026
+ 26 releases

Contributors

Languages