# LuaProtect MCP Server - Roblox Luau Scripting for AI Assistants

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue)](https://modelcontextprotocol.io)

A **Model Context Protocol (MCP) server for Roblox** that lets AI assistants - Claude Desktop, Claude Code, Cursor, Antigravity, Windsurf, or any other MCP client - execute and inspect **Luau / Lua code** directly inside a **live Roblox game session**, brokered through your [LuaProtect](https://luaprotect.dev) account.

Point your AI assistant at a running Roblox game and let it read live game state, inspect the local player, and run test scripts in real time - no manual copy-pasting between your editor and the executor console. This is the first publicly available Roblox Scripting MCP integration, built by the team behind [LuaProtect's Luau obfuscator and whitelist platform](https://luaprotect.dev).

## What it does

This repo has two halves that talk to each other over LuaProtect's API:

1. **The MCP server** (`bin/server.js`) - a stdio MCP server your AI client launches as a subprocess. It exposes four tools and forwards tool calls to LuaProtect's API.
2. **The Roblox bridge script** (`roblox/mcp_script.lua`) - a small script you run in your Roblox executor. It polls LuaProtect for pending commands, executes them in the live game session, and reports results back.

```
AI assistant  <--MCP (stdio)-->  luaprotect-mcp  <--HTTPS-->  api.luaprotect.dev  <--HTTPS poll-->  mcp_script.lua (in your executor)
```

Neither half ever talks to the other directly - everything is brokered through your authenticated LuaProtect account, so no inbound ports or local networking are required on your machine.

## Tools

| Tool | Description |
|---|---|
| `execute_script` | Runs a Lua source string inside the connected Roblox session and returns its output/errors. |
| `get_executor_status` | Reports whether the Roblox bridge is currently connected. |
| `get_game_info` | Returns the current place ID, job ID, place version, and player count. |
| `get_local_player` | Returns the connected player's username, display name, user ID, and account age. |

## Setup

### 1. Get an OAuth token

Authorize at [dashboard.luaprotect.dev/oauth/authorize?client_id=mcp-script](https://dashboard.luaprotect.dev/oauth/authorize?client_id=mcp-script) (requires a free LuaProtect account) and copy the token it gives you.

### 2. Run the bridge script in your executor

Paste this into your Roblox executor's console, replacing `YOUR_TOKEN`:

```lua
getgenv().LUAPROTECT_MCP_TOKEN = "YOUR_TOKEN"
loadstring(game:HttpGet("https://cdn.luaprotect.dev/mcp"))()
```

(That CDN URL always serves the current version of `roblox/mcp_script.lua` in this repo - the copy here is for reading/auditing, not something you need to host yourself.)

### 3. Clone this repo

```bash
git clone https://github.com/empfi/luaprotect-mcp.git
```

### 4. Configure your MCP client

**Claude Code / Claude Desktop** (`claude_desktop_config.json` or via `claude mcp add`):

```json
{
  "mcpServers": {
    "luaprotect": {
      "command": "node",
      "args": ["/absolute/path/to/luaprotect-mcp/bin/server.js"],
      "env": {
        "LUAPROTECT_OAUTH_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

**Cursor / other MCP clients** - same shape: run `node /absolute/path/to/luaprotect-mcp/bin/server.js` as the command, with `LUAPROTECT_OAUTH_TOKEN` set in the environment.

### Environment variables

| Variable | Required | Default |
|---|---|---|
| `LUAPROTECT_OAUTH_TOKEN` | Yes (or pass `token` per tool call) | - |
| `LUAPROTECT_API_URL` | No | `https://api.luaprotect.dev/api` |

## Security notes

- Your OAuth token is read from an environment variable, not from tool-call arguments, specifically so it never ends up sitting in an LLM's conversation transcript.
- `execute_script` runs arbitrary Lua inside your own Roblox session under your own account - treat it the same way you'd treat any other code an AI assistant asks to run on your behalf. Review scripts before letting an agent run them against anything that matters.
- The Roblox bridge only ever makes outbound HTTPS requests to `api.luaprotect.dev`; it does not open any listening ports.

## FAQ

**What is the LuaProtect Roblox Scripting MCP?**
It's a Model Context Protocol server that bridges AI coding assistants to a live Roblox client, so the assistant can run and test Luau/Lua scripts against real game state instead of guessing at behavior from static code alone.

**Do I need a LuaProtect account?**
Yes - a free account at [luaprotect.dev](https://luaprotect.dev) gets you the OAuth token this server needs. LuaProtect's free tier also includes its [Luau obfuscator, key system, and script manager](https://luaprotect.dev).

**Is this related to Luarmor or Luraph?**
No direct relation - LuaProtect is a separate platform and [Luarmor/Luraph alternative](https://luaprotect.dev/luarmor-alternative) with its own register-VM obfuscator, HWID whitelist keys, and live session telemetry. This MCP server is a standalone integration on top of it.

**Does this work with executors other than the ones I've tested?**
The bridge script (`roblox/mcp_script.lua`) uses the standard executor HTTP request API (`request`/`http_request`/`syn.request`/etc.), so it should work with most modern Roblox executors. Open an issue if yours doesn't.

## Links

- [LuaProtect](https://luaprotect.dev) - Roblox Luau obfuscator, whitelist service, and key system
- [Dashboard](https://dashboard.luaprotect.dev) - sign up / manage scripts
- [Documentation](https://docs.luaprotect.dev) - full API reference
- [Discord](https://discord.gg/DPA79awWnN) - support and community

## License

MIT