RoBridge
by Allusia1
README.md
# RoBridge
[](docs/README.md)
[](plugin/RoBridge.lua)
[](docs/tools.md)
[](LICENSE)
[](CHANGELOG.md)
A free, open, **local** MCP server that lets AI agents (Cursor, Claude, any MCP client) drive **Roblox Studio** — DataModel, scripts, terrain, lighting, UI, and playtests — plus a dashboard at [http://127.0.0.1:3737](http://127.0.0.1:3737). All tools included. No Pro tier.
Public MIT: fork for your own version, PRs welcome; `main` is maintained by LeapVerse/Allusia1.
```mermaid
flowchart LR
A["AI agent<br/>MCP stdio"] --> B["RoBridge server<br/>:3737"]
B --> C["Studio plugin"]
C --> D["Your place"]
B --> E["Dashboard"]
```
## Docs
Everything lives in this repo (no separate docs site):
| | |
| --- | --- |
| [Install](docs/install.md) | Build, plugin, HTTP, Mesh/Image APIs |
| [MCP setup](docs/mcp.md) | Cursor, Claude Desktop, Claude Code, generic stdio |
| [Playtesting](docs/playtesting.md) | `run_test`, Play/Run, input |
| [Dashboard](docs/dashboard.md) | Local UI on `:3737` |
| [Tools](docs/tools.md) | Full action + param reference |
| [Troubleshooting](docs/troubleshooting.md) | Fix lines, stuck Play |
| [Limits](docs/limits.md) | One port, InsertService, no Open Cloud |
| [Changelog](CHANGELOG.md) | Server 0.1.8 / plugin 0.1.9 |
Clone this repo, then `npm install` (see **First run**).
## Works with
Cursor, Claude Desktop, Claude Code, and any stdio MCP client (VS Code Copilot, Cline, Windsurf). Init writes the spawn config (absolute Node binary + absolute `dist/index.js`, empty argv). Details: [docs/mcp.md](docs/mcp.md).
## First run
```bash
npm install
```
Postinstall **builds** the server and runs **init**: copies the Studio plugin into the Roblox Plugins folder **and writes** Cursor / Claude MCP configs (merge — other servers are kept). Re-run later with `npx robridge init`. Plugin only: `npx robridge install-plugin`. Configs only: `npx robridge mcp`.
Then **reload MCP** in Cursor (Settings → MCP), **open Studio** (or refresh Plugins), **Allow HTTP** to `127.0.0.1`, and (for screenshots) **Allow Mesh / Image APIs**. Fully quit Claude Desktop if you use it. Clients spawn the server; you do not start it in a terminal. Stuck? `npx robridge doctor` prints a checklist (Node, dist, plugin, MCP config, :3737, Studio) and exactly one next step. Official Studio MCP (Assistant → **…** → **Enable Studio as MCP server**) is optional and complementary — it does not use `:3737` ([MCP setup](docs/mcp.md)).
Plugin destination:
| OS | Path |
| --- | --- |
| macOS | `~/Documents/Roblox/Plugins/RoBridge.lua` |
| Windows | `%LOCALAPPDATA%\Roblox\Plugins\RoBridge.lua` |
Unusual clients that cannot be auto-configured: [MCP setup](docs/mcp.md) (fallback JSON). Reload the MCP server after each rebuild (`npx robridge mcp` updates paths). Claude Desktop: fully quit and reopen.
Dashboard: [http://127.0.0.1:3737](http://127.0.0.1:3737). Dashboard only (you run this yourself): `node dist/index.js --no-mcp`.
One process owns `:3737`. Extra MCP clients (Cursor + Claude together) **forward** to that owner and share the same Studio session.
## Updating
Keep this clone. From the repo root:
```bash
npx robridge update
```
That runs `git pull --ff-only` then `npm install` (rebuild + init). The working tree must be clean. Then **reload MCP** and **refresh Studio plugins**. MCP/HTTP start also copies `plugin/RoBridge.lua` into the Roblox Plugins folder if it is missing or out of date. The dashboard shows a banner when a newer GitHub release exists.
## Tools (24, all free)
MCP `tools/list` and HTTP `/api/tools` share the same `defineTool` Zod shapes. Full param tables: [docs/tools.md](docs/tools.md).
| Tool | Actions |
| --- | --- |
| `query_instances` | get, children, descendants, ancestors, find_child, find_descendant, wait_for_child, search_class, search_name, search_property, search_tag, class_info, file_tree, project_structure |
| `mutate_instances` | create, create_with_props, delete, clone, move, rename, pivot, create_tree, mass_create, mass_delete, mass_duplicate, smart_duplicate, scatter |
| `manage_properties` | get, get_all, set, set_many / set_multiple, attributes/tags (incl. get_tagged, check_tag), set_relative, set_calculated, mass_set, mass_get, modify_children |
| `manage_scripts` | get_source, set_source, create, delete, list, search, replace, edit_lines, edit_replace, edit_insert, edit_delete, validate, get_dependencies |
| `manage_ui` | design_brief, create_tree, update, list, inspect, list_interactive, preview, hide_preview, click, type_text, scroll, get_abs, check, delete |
| `manage_lighting` | get, set / lighting, set_time / time, atmosphere, sky, terrain_props, mood, add_effect, clear_effects |
| `manage_selection` | get, set, add, remove, clear, details, cached, context, watch |
| `manage_camera` | get / info, set, focus / focus_path, focus_position, suggest, zoom_extents, screenshot, record, record_stop |
| `manage_tween` | create, play, pause, resume, cancel / stop_all |
| `manage_audio` | create, play, pause, resume, stop, stop_all, list, set, set_listener |
| `manage_animation` | create, list, load, play, stop, stop_all, get_tracks |
| `manage_physics` | anchor, unanchor, set_collide, weld, get_mass, set_physical_properties, create_constraint, register_group, set_collidable, get_groups |
| `manage_effects` | create, remove / clear, list, emit, toggle |
| `manage_terrain` | fill_block/ball/cylinder/wedge, clear, clear_region, clear_bounds, replace_material, colors_get/set, read/write voxels, generate, smooth, get_info |
| `spatial_query` | raycast, multi_raycast, in_radius, in_box, ground_height / find_ground, check_placement, scan_area, find_flat, find_spawn, analyze_walkable, spatial_map, find_space, bounds, snap_grid, collision |
| `manage_assets` | search, preview / info, insert / insert_free / insert_package, search_insert, export/import library, review_model, generate_model, upload_asset, generate_thumbnail |
| `manage_sync` | export_scripts, status / status_current_place, history, directions, read_file, write_file, progress |
| `workspace_state` | summary, counts, sync, snapshot, changes, clear_history, viewport, metadata, scripts, selection_info, clear_cache |
| `manage_logs` | get, errors, clear |
| `system_info` | info (default), ping, connection, place_info, services, usage, preflight |
| `manage_studio` | get_mode, play_status, play_start, play_stop, play_pause, play_resume, **run_test**, toggle_ui_preview, test_profile_get/set/reset, experience_language_get/set, undo, redo, set_waypoint, save_prompt |
| `manage_input` | click_at, click_path, key, type_text, walk_to, click_world, walk_and_click |
| `batch_execute` | run several tool calls in one request (optional waypoint / stopOnError) |
| `execute_luau` | run arbitrary Luau at plugin security level |
`manage_studio.run_test` injects Luau, **stops leftover Play first**, starts Play (or Run), collects `[ROBRIDGE_TEST]` logs, stops, and writes a report. Prefer it over `play_start` + `manage_logs` + `play_stop`.
`system_info.preflight` is a read-only Studio checklist (edit mode, HttpService, loadstring, Mesh/Image APIs) with fix instructions.
### Value conventions
Property values accept plain JSON: `[x,y,z]` for Vector3/CFrame position, 12 numbers for full CFrame, `"#ff0000"` or `[r,g,b]` for Color3, `[xs,xo,ys,yo]` for UDim2, `"Enum.Material.Neon"` or `"Neon"` for enums, path strings for Instance references.
Instance paths look like `game.Workspace.Model.Part` or `Workspace/Model/Part`. Prefer `rbId` from a prior summary when names collide. Never invent `rbxassetid` values — `manage_assets.search` first.
## Configuration
| Env var | Default | Purpose |
| --- | --- | --- |
| `ROBRIDGE_PORT` | `3737` | Dashboard + plugin bridge port |
The plugin reads `RoBridgeHost`/`RoBridgePort` plugin settings if you need a non-default port.
Dump the shipped catalog (no Studio needed): `node dist/index.js --dump-catalog`. Live HTTP: [http://127.0.0.1:3737/api/tools](http://127.0.0.1:3737/api/tools). Schema check: `npm run test:schema`.
## Troubleshooting
| Problem | What to do |
| --- | --- |
| No Studio session | Open the place in Studio with the plugin; click **Allow** for HTTP to `127.0.0.1`. |
| `execute_luau` / loadstring in Play | Edit-only. Use `run_test` / play agents, or `play_stop` first. |
| Stuck Play | Press **Stop** in Studio (or `manage_studio.play_stop`), then retry. |
| CaptureService / screenshot failed | File → Game Settings → Security → Allow Mesh / Image APIs. One in-flight shot; ~1.5–2 fps is expected. |
| Play started but agent never polls | Game Settings → Security → Allow HTTP Requests. |
| Stale dashboard / port in use | One process owns `:3737`. Stop the owner MCP/Node process and start once. |
Tool errors append a `Fix:` line when the server recognizes the failure. Run `system_info` `preflight` for a checklist. More: [docs/troubleshooting.md](docs/troubleshooting.md).
## Limits
- One RoBridge instance owns `:3737`; extra MCP clients **forward** to that owner.
- `manage_assets` insert uses `InsertService:LoadAsset` (asset must be free or owned by you).
- Open Cloud asset upload is not included. `upload_asset` is Studio `AssetService:CreateAssetAsync` (`confirm=true`).
See [docs/limits.md](docs/limits.md).
## Repository
| Path | |
| --- | --- |
| `src/` | MCP + HTTP server (`VERSION` 0.1.8) |
| `plugin/` | Studio plugin (`VERSION` 0.1.9) |
| `ui/` | Dashboard served at [http://127.0.0.1:3737](http://127.0.0.1:3737) |
| `docs/` | Install, MCP, playtesting, tools, limits |
| `scripts/` | Plugin install, catalog extract, tests |
`npm test` runs `test:schema` and `test:hints` (no Studio). Play/UI tests need an open place.
## License
MIT. See [LICENSE](LICENSE).
TDQS
B3.4/5.0
Scored across 24 tools
Disambiguation4/5
Each tool targets a distinct domain (terrain, instances, properties, scripts, lighting, etc.), but some overlap exists between query_instances and workspace_state for hierarchy inspection, and between manage_effects, manage_audio, and manage_animation for creating different instance types. Overall, tool purposes are clear enough to avoid frequent misselection.
Naming Consistency3/5
The naming convention is mixed: many tools use the manage_ prefix (manage_terrain, manage_scripts), but others use bare verbs or noun phrases (query_instances, spatial_query, workspace_state, system_info, execute_luau, batch_execute). While all names are lowercase with underscores, the lack of a uniform verb_noun pattern makes the set feel less predictable.
Tool Count3/5
With 24 tools, the count is at the high end of what is considered heavy (16-25). However, the server covers a very broad domain (Roblox Studio control), and each tool represents a major subsystem, so the count is borderline but arguably justifiable. It still feels dense and might overwhelm agents.
Completeness4/5
The tool set is highly comprehensive, covering instance management, terrain, lighting, camera, physics, UI, input, scripts, assets, animation, audio, and testing. Minor gaps exist, such as no dedicated tool for managing Game Settings or project-level configuration beyond preflight checks, but the core workflows for editing and testing a Roblox place are well covered.
Maintenance
ActivitySlowing
ResponsivenessNo issues