# rbx-mcp
[![npm version](https://img.shields.io/npm/v/@lolofuk123/rbx-mcp)](https://www.npmjs.com/package/@lolofuk123/rbx-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@lolofuk123/rbx-mcp)](https://www.npmjs.com/package/@lolofuk123/rbx-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![rbx-mcp MCP server](https://glama.ai/mcp/servers/lolofuk123/rbx-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lolofuk123/rbx-mcp)
> 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](docs/demo.gif)

## Status

Stable. Published on npm as [`@lolofuk123/rbx-mcp`](https://www.npmjs.com/package/@lolofuk123/rbx-mcp).
Design docs and the phased build plan live in [`work/`](https://github.com/lolofuk123/rbx-mcp/blob/main/work);
start with [`work/README.md`](https://github.com/lolofuk123/rbx-mcp/blob/main/work/README.md) and the concept doc [`PROJECT_CONCEPT_1.md`](https://github.com/lolofuk123/rbx-mcp/blob/main/PROJECT_CONCEPT_1.md).

## 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](https://nodejs.org) ≥ 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`:
```json
{
  "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**):
```json
{
  "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`](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](https://nodejs.org) ≥ 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
# bash / macOS / Linux
RBXMCP_DEV=1 npx -y @lolofuk123/rbx-mcp
```
```powershell
# 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`:
  ```json
  {
    "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

```bash
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`](LICENSE).