Roblox Studio MCP

A production Model Context Protocol (MCP) integration that lets AI agents control Roblox Studio and autonomously build, test, and debug Roblox games.

With this project connected, an AI assistant (Claude, Cursor, Claude Code, or any MCP client) can operate like a full Roblox development team — programmer, level designer, UI developer, gameplay engineer, tester, and debugger — inside a live Studio session:

• 🌳 Explorer control — create, inspect, clone, move, rename, and delete instances; batch-build hundreds of objects with one undo waypoint; bulk mass_set_properties across a whole map

• 📜 Script management — create/read/edit/patch/search/refactor Script, LocalScript, and ModuleScript; project-wide find_and_replace_in_scripts with dry-run; compile-check the whole place

• ⚙️ Code execution — run arbitrary Luau in Studio (plugin security level) with captured output and serialized return values

• 🐞 Runtime debugging — during play-solo / multiplayer tests every DataModel connects as its own peer: eval_server_runtime / eval_client_runtime inspect live game state mid-playtest, per-peer get_output_logs / get_errors read each side's logs (including boot-time prints), and set_log_breakpoint instruments code without pausing

• 🧪 Test & debug loop — start/stop playtests, read output logs and errors with Luau stack traces, fix, and retest — fully autonomously

• 📚 Official API docs — get_roblox_docs fetches real Roblox engine reference (classes, datatypes, enums) so the agent checks ProximityPrompt or CFrame semantics instead of hallucinating them

• 🌍 World building — procedural terrain (Perlin-noise hills, blocks, spheres), lighting presets, catalog asset insertion, camera control

• 🧩 Game system scaffolds — one command installs production-grade systems: DataStore player profiles, currencies, inventory, shop, quests, progression + achievements, global leaderboards, combat, NPCs, round/matchmaking loops, settings, and a themed UI kit (HUD, menus, notifications)

• 🌐 Every MCP client — stdio for local clients (Claude Code, Claude Desktop, Cursor, Codex, Gemini) plus a Streamable HTTP transport (--transport http) for AI platforms that only accept a server URL, publishable through Cloudflare Tunnel / ngrok / Tailscale (docs/remote-access.md)

• 🔐 Security-first — bearer-token authentication on both the plugin bridge and the HTTP MCP endpoint, localhost-only binds by default, command validation, rate-limited remotes in generated code, script-stripping on asset inserts

Architecture

AI Agent (Claude / Cursor / URL-only platforms / any MCP client)
        │  MCP over stdio  — or —  Streamable HTTP at /mcp (bearer token)
        ▼
MCP Server (Node.js + TypeScript)
        │  local HTTP bridge on 127.0.0.1 (bearer-token auth)
        ▼  long-polling (plugins can only make outbound requests)
Roblox Studio Plugin (Luau) — one peer per DataModel:
   ├─ edit session            (building + Run-mode simulation)
   ├─ playtest server         (eval_server_runtime, server logs)
   └─ playtest client(s)      (eval_client_runtime, client logs)
        │  command executors + ChangeHistory waypoints
        ▼
Roblox Studio (your open place)

See ARCHITECTURE.md for the full design, protocol, data flow, and security model.

Related MCP server: Roblox MCP

Quick start

1. Requirements

• Node.js ≥ 18.17

• Roblox Studio

• An MCP client (Claude Desktop, Claude Code, Cursor, …)

2. Install & build

git clone https://github.com/Meganugger/roblox-studio-mcp.git
cd roblox-studio-mcp
npm install
npm run build

This builds the server, the shared package, and the Studio plugin artifact at studio-plugin/dist/RobloxStudioMCP.rbxmx.

3. Install the Studio plugin

One command:

node server/dist/index.js --install-plugin

This copies the built plugin into your local Studio plugins folder (Windows: %LOCALAPPDATA%\Roblox\Plugins, macOS: ~/Documents/Roblox/Plugins; override with MCP_PLUGINS_DIR). Fully close and reopen Studio afterwards. Manual alternative: drop studio-plugin/dist/RobloxStudioMCP.rbxmx into the same folder.

4. Connect your AI client

Add the server to your MCP client config. Claude Desktop (claude_desktop_config.json):

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

Claude Code:

claude mcp add roblox-studio -- node /absolute/path/to/roblox-studio-mcp/server/dist/index.js

More client configs in examples/client-configs/.

5. Pair Studio with the server

1. Start your MCP client — the server prints its auth token to stderr on startup (also saved at ~/.roblox-studio-mcp/token).

2. In Roblox Studio, open your place and click the MCP toolbar button.

3. Paste the token into the widget and press Connect. (The plugin needs Allow HTTP Requests; it enables it for you when possible.)

4. Ask your AI: "Check the Roblox Studio connection" → it calls get_studio_status. ✅

6. Build a game

Try the acceptance prompt:

"Create a polished Roblox simulator game."

The agent will lay out the map with generate_terrain + create_instances_batch, install data profiles/currency/shop/quests/UI with install_scaffold, write game-specific scripts, then loop analyze_scripts → start_playtest → get_errors → fix → retest until everything runs clean. A full walkthrough lives in examples/simulator-game.md.

Tool suite (48 tools)

Full reference with parameters and examples: docs/tools.md.

Runtime debugging (per-peer)

When the user starts a play-solo or multiplayer playtest (F5 / Test tab), Studio runs the plugin inside every DataModel. Each auto-connects with the saved token as its own peer, so the agent can:

get_connected_peers                → edit + server + client:Player1 (+ client:Player2 …)
eval_server_runtime  code=…        → inspect live server state (e.g. MatchService round data)
eval_client_runtime  code=…        → inspect a client's PlayerGui / camera / character
get_output_logs      peer=server   → server-side logs incl. boot-time prints
get_errors           peer=client   → client-side errors with Luau stack traces
set_log_breakpoint   path=… line=… → instrument code without pausing, reproduce, read logs

Ask things like: "Start reading the server logs, reproduce the hit, and tell me why the damage function never fires" — the agent sets a log breakpoint, reads per-peer logs, and fixes the code.

Remote URL access (URL-only AI platforms)

Some AI platforms can't spawn a local process and only accept an MCP server URL. Run:

node server/dist/index.js --transport http

This serves the full tool suite over Streamable HTTP at http://127.0.0.1:3668/mcp, protected by a bearer token (printed on startup; persisted at ~/.roblox-studio-mcp/http-token). Publish it with a reverse tunnel — no inbound firewall holes, TLS terminated by the tunnel:

cloudflared tunnel --url http://127.0.0.1:3668     # or ngrok http 3668 / tailscale funnel 3668

Then give the platform https://<your-tunnel-host>/mcp with header Authorization: Bearer <http-token>. Full guide, security model and provider comparison: docs/remote-access.md.

Configuration

Environment variables read by the server:

Repository layout

server/         MCP server: tools, HTTP bridge, auth, scaffold library (TypeScript)
studio-plugin/  Roblox Studio plugin: bridge loop, executors, UI (Luau, Rojo-compatible)
shared/         Wire protocol, command names, property encoding (TypeScript)
scripts/        Plugin packer (source tree → .rbxmx)
tests/          Vitest suite incl. full-stack MCP + bridge integration tests
docs/           Installation, usage, tool reference, troubleshooting
examples/       Client configs, prompt playbooks, simulator-game walkthrough

Development

npm run typecheck   # strict TS across workspaces
npm test            # 62 tests: unit + multi-peer bridge + HTTP transport + MCP client integration
npm run build       # server + shared + plugin artifact

The plugin sources are Rojo-compatible (studio-plugin/default.project.json), so rojo build studio-plugin -o RobloxStudioMCP.rbxmx produces an equivalent artifact if you prefer the Rojo toolchain. Every Luau file (plugin + all generated scaffold code) compiles clean with the official Luau compiler; the test suite verifies this when luau-compile is available.

Troubleshooting

Common issues (plugin won't connect, HTTP disabled, token mismatch, port conflicts, playtest caveats) are covered in docs/troubleshooting.md.

Prior art & attribution

This project builds on the architecture proven by Roblox/studio-rust-mcp-server (official, Rust) and boshyxd/robloxstudio-mcp (TypeScript) — in particular the stdio-MCP + local-HTTP-bridge + long-polling-plugin pattern that works within Roblox Studio's outbound-only HTTP constraint. The per-peer runtime-debugging model (one plugin peer per playtest DataModel) was pioneered by Chrrxs/robloxstudio-mcp. This implementation is written from scratch and combines those ideas with token authentication, atomic batch building, a script patch/refactor toolchain, an autonomous test/debug loop, log breakpoints, official-docs lookup, a Streamable HTTP transport for URL-only platforms, and a production gameplay scaffold library.

License

MIT