Skip to main content
Glama

rbx-mcp

npm version npm downloads License: MIT rbx-mcp MCP server

Let an AI agent (Claude) write Lua and execute it live inside Roblox Studio, read the result, and iterate — over the Model Context Protocol.

rbx-mcp is a small bridge with two halves in one process:

  • an MCP server (stdio) that exposes Studio actions to Claude as tools (execute_lua, read_studio_state, get_errors), and

  • a localhost HTTP server that a tiny Roblox Studio plugin polls — it runs the Lua via loadstring() and reports back output, return values, and errors (with tracebacks).

The plugin is deliberately dumb and universal: it just runs whatever Lua it's given, so it never needs updating for new tasks. All the intelligence stays on the AI side.

rbx-mcp demo

Status

Stable. Published on npm as @lolofuk123/rbx-mcp. Design docs and the phased build plan live in work/; start with work/README.md and the concept doc PROJECT_CONCEPT_1.md.

Related MCP server: dex-mcp

Repo layout

server/   Node/TS package, published to npm as `rbx-mcp`
          (MCP side + localhost HTTP side; bundles & auto-installs the plugin)
plugin/   single-file Studio plugin: src/rbx-mcp.server.luau (no build step)
work/     specs + implementation plan

Setup

Prerequisites: Node.js ≥ 20, Roblox Studio, and an MCP-capable AI host (see below). rbx-mcp is model-agnostic — bring Claude, GPT, or any model your host drives; the server only exposes MCP tools, the model just calls them. The host must run a local stdio server on the same machine as Studio (the plugin talks to localhost).

1. Add the MCP server to your AI host

Claude Desktop / Claude Code — top-level key mcpServers:

{
  "mcpServers": {
    "rbx-mcp": { "command": "npx", "args": ["-y", "@lolofuk123/rbx-mcp"] }
  }
}
  • Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).

  • Claude Code: .mcp.json at the project root, or claude mcp add rbx-mcp -- npx -y @lolofuk123/rbx-mcp.

VS Code / GitHub Copilot (agent mode) — note the different key (servers) and type. File .vscode/mcp.json (or Command Palette → MCP: Add Server):

{
  "servers": {
    "rbx-mcp": { "type": "stdio", "command": "npx", "args": ["-y", "@lolofuk123/rbx-mcp"] }
  }
}

(Cursor / Windsurf are similar — e.g. .cursor/mcp.json, same mcpServers shape as Claude.)

2. Open Roblox Studio

On first launch the server auto-installs the plugin into your local Plugins folder; Studio loads it on (re)start. Then open the rbx-mcp panel → click Start. If HttpService is off, the panel tells you exactly where to enable it (Experience settings → Security → Allow HTTP Requests); it connects automatically once you do.

That's it. See server/README.md for env vars, an optional auth token, and manual plugin install.

Setup on a managed / corporate machine (Claude Code)

On org-managed machines, enterprise policy often blocks Claude Code from registering MCP servers (both claude mcp add and .mcp.json loading). The workaround: start the server yourself with the dev route enabled, then let Claude Code drive Studio via direct HTTP calls instead of MCP tools.

Prerequisites

  • Node.js ≥ 20 installed

  • Roblox Studio installed

  • Claude Code CLI

Step 1 — Start the server manually

Open a terminal (keep it running in the background) and start the server with the dev route enabled:

# bash / macOS / Linux
RBXMCP_DEV=1 npx -y @lolofuk123/rbx-mcp
# PowerShell (Windows)
$env:RBXMCP_DEV=1; npx -y @lolofuk123/rbx-mcp

On first run the server writes the Studio plugin into your local Plugins folder:

%LOCALAPPDATA%\Roblox\Plugins\rbx-mcp.lua   (Windows)
~/Documents/Roblox/Plugins/rbx-mcp.lua       (macOS)

Step 2 — Open Roblox Studio and connect the plugin

  1. Restart Studio — it only scans the Plugins folder at launch, so a full restart is required after the first run in Step 1.

  2. Enable HttpService — Game Settings → Security → Allow HTTP Requests. The plugin cannot do this for you; it is a one-time manual step per experience.

  3. Open the rbx-mcp panel (Plugins toolbar) → click Start.

Verify in a browser that both sides are up:

http://127.0.0.1:30700/v1/health

"pluginConnected": true means you're ready.

Step 3 — Tell Claude Code to use the dev route

Because MCP tools are blocked, Claude Code executes Lua by posting directly to the server's dev endpoint. Tell Claude Code at the start of your session:

"The rbx-mcp server is running with RBXMCP_DEV=1. MCP tools are blocked by policy on this machine. Execute Lua in Studio by posting to http://127.0.0.1:30700/v1/_dev/enqueue with body {"code": "..."} and reading the result from the response."

Claude Code uses its PowerShell or Bash tool to POST to that endpoint and reads the result synchronously from the response — no MCP handshake needed. You're live.

Troubleshooting

VS Code / Copilot (Windows):

  • MCP tools don't appear / no "Start" shows up — MCP tools only work in Copilot Agent mode (not Ask/Edit). Start the server via Command Palette → MCP: List Servers → rbx-mcp, and enable it in the chat's 🔧 Tools picker.

  • node/npx "not recognized" in VS Code's terminal (but fine in a normal terminal) — VS Code launched with a stale PATH from before Node was installed. Fully quit and reopen VS Code (reboot if it persists) so it picks up Node.

  • spawn npx ENOENT when starting the server — on Windows npx is actually npx.cmd, which VS Code's direct spawn can miss. Wrap it in cmd:

    {
      "servers": {
        "rbx-mcp": { "type": "stdio", "command": "cmd", "args": ["/c", "npx", "-y", "@lolofuk123/rbx-mcp"] }
      }
    }

    (or set "command": "npx.cmd").

Roblox Studio:

  • No rbx-mcp toolbar button after install — fully restart Studio; it only scans the Plugins folder at launch. (The installed file must be .lua, which the auto-installer handles.)

  • Stuck on "HTTP service disabled" — enable it (Experience settings → Security → Allow HTTP Requests); the plugin connects automatically once it's on.

  • pluginConnected: false in /v1/health — open the rbx-mcp panel and click Start; check Host/Port (and Token, if set) match the server.

Development

cd server
npm install
npm test          # vitest
npm run build     # tsc -> dist/
npm run dev       # run the server locally (stdio MCP + HTTP on 127.0.0.1:30700)

License

See LICENSE.

Available Tools

3 tools
execute_luaExecute Lua in Roblox StudioA

Run a Luau code string inside Roblox Studio (via loadstring) and return its captured output, return values, and any error with traceback. Use this to build, script, inspect, or modify anything in Studio; iterate by reading the error and re-running.

Inputs: code (required), label, timeoutMs.

get_errorsRecent execution errorsA

Return the most recent failed executions (message + traceback). Useful for recovering context.

Inputs: limit.

read_studio_stateRead Roblox Studio stateA

Inspect Studio state in a clean form: 'selection' (current selection), 'explorer_tree' (workspace tree to a depth), 'instance' (one instance by dotted path, e.g. 'Workspace.Model.Part'), or 'services_summary'. Runs a server-owned snippet — no arbitrary code.

Inputs: query (required), path, depth.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: execute_lua runs arbitrary code, read_studio_state provides structured read-only inspection, and get_errors surfaces recent failures. No overlap or ambiguity.

    Naming Consistency5/5

    All three tool names follow the same verb_noun pattern in snake_case (execute_lua, read_studio_state, get_errors). The naming is uniform and predictable.

    Tool Count5/5

    Three tools is well-scoped for this server. execute_lua acts as a powerful general-purpose action tool, while the other two provide safe inspection and error recovery, so no extra tools are needed.

    Completeness5/5

    execute_lua can perform any build, script, or modification task within Roblox Studio, read_studio_state covers structured inspection needs, and get_errors closes the debugging loop. The set covers the full workflow without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Debug and inspection tooling for Roblox projects, exposed as an MCP server so an AI agent can explore the instance tree, read/write properties, call remotes, and run Luau in a Roblox client driven by an executor.
      14
      14 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Debug and inspection tooling for Roblox projects, exposed as an MCP server so an AI agent can explore the instance tree, read/write properties, call remotes, and run Luau in a Roblox client driven by an executor.
      14
      14 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to control Roblox Studio by running Luau code, creating and editing instances, reading the scene tree, and managing scripts via an MCP server with a long-polling plugin bridge.
      MIT