Superbase

Superbase is a local Model Context Protocol (MCP) server that connects AI assistants to a running Roblox session through your executor. The AI can read the console and script errors, search and inspect the instance tree, read scripts, change properties and run Lua, and it always knows whether Roblox is actually connected.

• Zero configuration. No token, no account, no copy and paste. Start the bridge, run one line in your executor, add the MCP server to your AI client.

• Connection aware. Every tool result starts with a status line. When the game is not connected, the AI gets the exact script you need to run and tells you.

• 11 tools for logs, errors, inspection, scripts, properties and code execution.

• Works with any MCP client that supports stdio servers: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Codex CLI, Antigravity and more.

• Local only. Everything listens on 127.0.0.1. Web pages cannot reach it.

• No dependencies in the MCP server. The bridge needs only ws.

Warning. Superbase lets an AI run code inside your game with your executor's full permissions. Only connect AI clients you trust. See Security.

Contents

• How it works

• Requirements

• Quick start

• Connect your AI client

• Example prompts

• Tools reference

• Connection states

• The in-game client

• Configuration

• Token mode

• HTTP API

• Security

• Project layout

• Development

• Troubleshooting

• FAQ

Related MCP server: Roblox Executor MCP

How it works

Three small programs talk to each other on your computer:

flowchart LR
    AI["AI client<br/>(Claude Desktop, Cursor, ...)"]
    MCP["src/mcp-server.js<br/>MCP server"]
    Bridge["src/bridge.js<br/>bridge"]
    Client["roblox/client.lua<br/>in your executor"]

    AI -- "stdio (MCP)" --> MCP
    MCP -- "HTTP, 127.0.0.1" --> Bridge
    Client -- "WebSocket, 127.0.0.1" --> Bridge

Because the bridge stores logs, the AI can still read what happened after you leave the game.

Requirements

• Node.js 18 or newer

• A Roblox executor that supports WebSocket.connect and loadstring

• An AI client that supports MCP servers over stdio

Quick start

1. Install and start the bridge

git clone https://github.com/fiangg20/superbase.git
cd superbase
npm install
npm start

The bridge prints the loader for your executor:

[superbase] bridge 1.2.0 listening on ws://127.0.0.1:9731 (HTTP API on the same port)
[superbase] load the client in your executor with: loadstring(game:HttpGet("http://127.0.0.1:9731/client.lua"))()

2. Load the client in your game

Join a game and run this in your executor:

loadstring(game:HttpGet("http://127.0.0.1:9731/client.lua"))()

The intro plays, the console prints [Superbase] Connected and authenticated and a Connected notification appears in the top right corner.

If your executor blocks HttpGet to localhost, paste the contents of roblox/client.lua into the executor instead.

3. Add Superbase to your AI client

Add the server to your client's MCP configuration (for Claude Desktop, see below for the other clients):

{
  "mcpServers": {
    "superbase": {
      "command": "node",
      "args": ["C:\\path\\to\\superbase\\src\\mcp-server.js"]
    }
  }
}

Restart the client, then ask: "Check the Roblox connection." The AI calls roblox_status and answers.

You do not have to remember the loader line. While no game is connected, every tool result from the AI contains it, and the AI shows it to you.

Connect your AI client

The command is always node with the absolute path to src/mcp-server.js. Use your own path in every example. If you changed the port, add "env": { "SUPERBASE_PORT": "<port>" }.

The formats below follow each client's documented MCP configuration, which can change. If one does not work, check that client's own documentation.

Open Settings → Developer → Edit Config, or edit claude_desktop_config.json (on Windows usually in %APPDATA%\Claude). Restart Claude Desktop afterwards.

{
  "mcpServers": {
    "superbase": {
      "command": "node",
      "args": ["C:\\path\\to\\superbase\\src\\mcp-server.js"]
    }
  }
}

If Claude Desktop keeps asking for permission, check the permission mode of the tool. Manual mode asks before every use of a new tool.

claude mcp add superbase -- node /path/to/superbase/src/mcp-server.js

These clients use the same shape as Claude Desktop.

{
  "mcpServers": {
    "superbase": {
      "command": "node",
      "args": ["/path/to/superbase/src/mcp-server.js"]
    }
  }
}

Since June 18, 2026 Gemini CLI no longer serves Google AI Pro, Ultra or free individual accounts. It still works with an API key or an enterprise license. Everyone else should use the Antigravity CLI.

Open the … menu at the top of the agent side panel, choose MCP Servers, then Manage MCP Servers and View raw config. That opens mcp_config.json. The documentation lists ~/.gemini/config/mcp_config.json for all projects and .agents/mcp_config.json for a single workspace. In the Antigravity CLI, type /mcp to open the MCP manager, or edit the same file directly.

{
  "mcpServers": {
    "superbase": {
      "command": "node",
      "args": ["/path/to/superbase/src/mcp-server.js"]
    }
  }
}

Click Refresh in Manage MCP Servers afterwards.

Add this to .vscode/mcp.json:

{
  "servers": {
    "superbase": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/superbase/src/mcp-server.js"]
    }
  }
}

Add this to ~/.codex/config.toml:

[mcp_servers.superbase]
command = "node"
args = ["/path/to/superbase/src/mcp-server.js"]

Clients that cannot use Superbase. Superbase is local. Cloud hosted AI chats and mobile or web apps cannot reach localhost, so they cannot use it. An AI that has no MCP support but can run shell commands can use the HTTP API directly.

Example prompts

Once connected, you can ask things like:

• "Check the Roblox connection."

• "Which game am I in, and who else is in the server?"

• "Show me the latest script errors and explain what causes them."

• "Find every RemoteEvent in ReplicatedStorage."

• "Read the source of game.StarterPlayer.StarterPlayerScripts.CameraScript and tell me what it does."

• "Set the Transparency of game.Workspace.Door to 0.5."

• "Run my code, then wait until the console prints Loaded and tell me what happened."

Tools reference

Every result starts with a status line, for example:

[Superbase] ● connected — place 123456, executor_name 3.2, 12 ms

Tools marked needs game only run in the connected state. The others work as soon as the bridge is up, so the AI can still read stored logs and errors after you left the game.

roblox_status

Pings the Roblox client and returns the connection state, place, executor, latency and the number of stored logs and errors. While waiting_for_roblox it also returns the loader script. Call it first. No parameters.

get_game_info · needs game

Place name and creator, job id, the local player, the player list (up to 50) and performance (physics FPS, memory, ping). No parameters.

find_instances · needs game

Searches the instance tree. At least one of name and class_name is required.

Returns the full path and class of each match and whether the list was cut off.

inspect_instance · needs game

Reads one instance.

Returns the class, the requested properties and up to 100 children.

get_script_source · needs game

Reads the source of a Script, LocalScript or ModuleScript. It uses the executor's decompile when available and falls back to the Source property.

set_property · needs game

Sets a property on an instance. This changes the game on your client, so it only replicates where Roblox allows it. Returns the old and the new value.

Supported values:

null is not accepted. Use execute_lua to set a property to nil.

execute_lua · needs game

Runs Lua in the executor and returns the serialized return values, or the error with a traceback.

Tables are serialized up to 4 levels deep and 50 entries per table. Strings are cut at 60,000 characters.

get_logs

Reads stored console output. The newest entries come last. The result contains a now timestamp you can pass as since next time.

get_errors

Reads stored script errors with the stack trace and the script path.

wait_for_log

Waits until a new console line (or script error) that contains some text appears, then returns it. Lines that were already stored when the call started do not count. A timeout is a normal result (matched: false), not an error.

clear_logs

Clears the stored logs and errors. No parameters.

Limits

Connection states

The AI always knows which state it is in, because the first line of every result shows it.

When the state is not connected, tools that need the game are not run, and the AI is told not to retry in a loop.

The bridge pings the client every 10 seconds and drops it after 30 seconds of silence, so a force closed game does not look connected.

The in-game client

roblox/client.lua does more than relay messages.

Intro. A short animated intro plays when the client starts. It does not delay the connection.

Notifications. Small toasts appear in the top right corner:

Toasts wait for the intro to finish.

Re-running is safe. Running the script again stops the previous instance first (including the older DebugBridge build), so connections do not stack.

Client settings

Edit the CONFIG table at the top of roblox/client.lua.

Configuration

Environment variables. Set them for the process that uses them: the bridge is started by you, the MCP server by your AI client (use the env field of its config).

To change the port, set SUPERBASE_PORT when you start the bridge and in the env of your MCP config, then use the loader the bridge prints. Example for PowerShell: $env:SUPERBASE_PORT="9800"; npm start.

Token mode

By default the bridge needs no token. If you want one anyway, for example because other programs run on your computer that you do not trust:

1. Generate a token: node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"

2. Start the bridge with it. PowerShell: $env:BRIDGE_TOKEN="<token>"; npm start. macOS or Linux: BRIDGE_TOKEN=<token> npm start.

3. Add it to your MCP config: "env": { "BRIDGE_TOKEN": "<token>" }.

4. Copy roblox/client.lua into your executor and set CONFIG.Token to the same token.

In token mode /client.lua is not served, so there is no loadstring loader. Never commit a real token.

HTTP API

The MCP server uses this API, and so can your own tools. In open mode every request needs a header named x-superbase-client (any value). In token mode it needs x-bridge-token: <token> instead. GET /client.lua needs neither.

Example:

curl -H "x-superbase-client: curl" "http://127.0.0.1:9731/status?probe=1"

Security

Superbase gives an AI the same power over your game client as your executor has. Read this section before you use it.

• Code execution. execute_lua and set_property run code inside your executor. Review what the AI wants to run before you approve it, and only connect clients you trust.

• Local only. The bridge binds to 127.0.0.1. Never expose the port to a network or the internet.

• Web pages are blocked. The bridge checks the Host header, rejects any HTTP request or WebSocket connection that carries a foreign Origin, never approves a CORS preflight and requires a custom header on every API call. A web page you visit cannot reach it.

• Other programs are not blocked in open mode. Without a token, any program running on your computer can use the bridge. Use token mode if that matters to you.

• Keep tokens private. Anyone who has the token and can reach the port can run code in your game. Never commit one.

• Use it in your own games. Running code in other people's games can break their rules. You are responsible for where you use Superbase.

Project layout

superbase/
├── src/
│   ├── bridge.js           WebSocket server and local HTTP API
│   ├── mcp-server.js       MCP server (stdio), no dependencies
│   └── lua/                Lua snippets behind the higher level tools
│       ├── game_info.lua
│       ├── find_instances.lua
│       ├── get_script_source.lua
│       └── set_property.lua
├── roblox/
│   └── client.lua          Runs in the executor
├── test/
│   ├── bridge.test.js
│   └── mcp-server.test.js
├── package.json
└── README.md

Development

npm install
npm test

The tests start the bridge, the MCP server and a fake executor, and cover every connection state, every tool, the open and token modes and the protection against web pages.

The Lua files (roblox/client.lua and src/lua/*.lua) need a real executor, so they are not covered by the tests. Test changes to them in a game.

To add a tool that runs Lua in the game, put the code in src/lua/<name>.lua (it receives its arguments as a table named args and returns a table, or { error = "..." } to fail), then add the tool definition in src/mcp-server.js and call runSnippet("<name>", args).

Compatibility notes

• The MCP server targets protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

• Executors differ. decompile, identifyexecutor and the WebSocket API are optional or named differently in some of them, and the client falls back where it can.

Troubleshooting

FAQ

Do I need Claude Code? No. Any MCP client that supports stdio servers works.

Does it work from my phone? No. The MCP server runs on your computer, so the AI client must run there too. Mobile and web apps cannot reach localhost.

Do I need a token? No. Open mode works without one and still blocks web pages. Use token mode if you want other programs on your computer to be locked out as well.

Can it change things on the server? Not by itself. Code runs on your client. Server side effects are possible only where the game itself exposes them, for example through a RemoteEvent that you own and that accepts code, which is your decision in your own game.

Does it work in every game? It works wherever your executor can run scripts. Some games detect or block executors, and that is outside the control of Superbase.

Is it affiliated with Roblox? No. Superbase is an independent project.