Installation

This guide covers all installation methods for RbxGenie, including development setup, production builds, and MCP server configuration.

System Requirements

Node.js

Version 18 or higher required

Roblox Studio

Latest version recommended

Operating System

Windows, macOS, or Linux

Git

For cloning the repository

Development Setup

For active development with hot-reload and TypeScript compilation.

Clone the repository

git clone https://github.com/nnaridz/RbxGenie.git
cd RbxGenie

Install dependencies

npm install

This installs:

express - HTTP server
@modelcontextprotocol/sdk - MCP protocol support
uuid - Command ID generation
zod - Schema validation
TypeScript and development tools

Start the daemon in development mode

npm run dev

This uses ts-node-dev for automatic restarts on file changes.

Development mode provides better error messages and source maps.

Bundle and install the plugin

npm run bundle:install

This bundles the plugin and copies it to your Roblox Plugins folder.

Development setup complete! The daemon will restart automatically when you modify TypeScript files.

Production Build

For deployment or standalone distribution.

Daemon Executable

Build a standalone executable that doesn’t require Node.js:

Windows (BUILD.cmd)
Manual Build

Run the provided build script:

BUILD.cmd

This script:

Bundles the plugin → dist/RbxGenie.plugin.lua
Copies plugin to %LOCALAPPDATA%\Roblox\Plugins\RbxGenie.lua
Compiles TypeScript → .build/ directory
Packages daemon → dist/RbxGenie.exe (using @yao-pkg/pkg)
Cleans up temporary files

The EXE is self-contained and can be distributed without Node.js installed.

Build TypeScript

npm run build

Compiles TypeScript to dist/ directory.

Bundle the plugin

npm run bundle

Creates dist/RbxGenie.plugin.lua.

Package to executable (optional)

npx @yao-pkg/pkg dist/server.js --targets node18-win-x64 --output dist/RbxGenie.exe --compress GZip

Replace node18-win-x64 with:

node18-macos-x64 for macOS Intel
node18-macos-arm64 for macOS Apple Silicon
node18-linux-x64 for Linux

Plugin Installation

Install the bundled plugin to Roblox Studio:

Windows
macOS
Linux

Copy dist/RbxGenie.plugin.lua to:

%LOCALAPPDATA%\Roblox\Plugins\RbxGenie.lua

Or use the npm script:

npm run bundle:install

Copy dist/RbxGenie.plugin.lua to:

~/Documents/Roblox/Plugins/RbxGenie.lua

Copy dist/RbxGenie.plugin.lua to:

~/.local/share/Roblox/Plugins/RbxGenie.lua

Exact path may vary depending on your Roblox installation method.

You must restart Roblox Studio after installing or updating the plugin.

MCP Server Setup

Enable RbxGenie as an MCP server for Claude Desktop or Cursor.

The daemon must be running before you can use the MCP server.

Automatic Configuration

The easiest way to set up MCP integration:

Start the daemon

npm run dev

The daemon must be running for MCP to work.

Build the MCP server

npm run build

Run the auto-installer

npm run install-mcp

This automatically configures:

Claude Desktop (%APPDATA%/Claude/claude_desktop_config.json)
Cursor (%APPDATA%/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json)

Restart your editor

Restart Claude Desktop or Cursor to load the new MCP server.

You should now see RbxGenie tools available in Claude or Cursor!

Manual MCP Configuration

If the auto-installer doesn’t work, configure manually:

Claude Desktop
Cursor / Cline
Other MCP Clients

Edit %APPDATA%/Claude/claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

claude_desktop_config.json

{
  "mcpServers": {
    "RbxGenie": {
      "command": "node",
      "args": ["C:/path/to/RbxGenie/dist/mcp.js"]
    }
  }
}

Replace C:/path/to/RbxGenie with your actual installation path.

Use forward slashes (/) even on Windows in the JSON configuration.

Edit Cline MCP settings at:Windows: %APPDATA%/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.jsonmacOS: ~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

cline_mcp_settings.json

{
  "mcpServers": {
    "RbxGenie": {
      "command": "node",
      "args": ["/path/to/RbxGenie/dist/mcp.js"]
    }
  }
}

Any MCP-compatible client can connect to RbxGenie:

{
  "mcpServers": {
    "RbxGenie": {
      "command": "node",
      "args": ["/absolute/path/to/RbxGenie/dist/mcp.js"],
      "env": {
        "RBXGENIE_PORT": "7766"
      }
    }
  }
}

The MCP server communicates with the daemon via HTTP, so the daemon must be running.

Verify MCP Installation

Test that MCP is working:

Start the daemon: npm run dev
Open Roblox Studio with a place
Open Claude Desktop or Cursor
Try asking: “Use RbxGenie to get the place info”

Claude should call the get_place_info tool and return your place information.

Package.json Scripts Reference

All available npm scripts:

Script	Command	Description
`dev`	`ts-node-dev --respawn --transpile-only src/server.ts`	Start daemon with hot-reload
`build`	`tsc`	Compile TypeScript to `dist/`
`start`	`node dist/server.js`	Run compiled daemon
`mcp`	`node dist/mcp.js`	Run MCP server (requires built code)
`install-mcp`	`ts-node src/install.ts`	Auto-configure Claude/Cursor
`bundle`	`node scripts/bundle.js`	Bundle plugin to `dist/RbxGenie.plugin.lua`
`bundle:install`	`node scripts/bundle.js && copy ...`	Bundle and install plugin (Windows)

File Structure

After installation, your directory should look like this:

RbxGenie/
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── BUILD.cmd              # Windows build script
├── START.cmd              # Windows start script
├── src/
│   ├── server.ts          # Main daemon entry point
│   ├── bridge.ts          # Command queue + event bridge
│   ├── mcp.ts             # MCP protocol implementation
│   ├── install.ts         # MCP auto-installer
│   └── types.ts           # TypeScript type definitions
├── plugin/
│   ├── init.server.lua    # Plugin bootstrap
│   ├── Bridge.lua         # HTTP long-poll loop
│   ├── Executor.lua       # Tool dispatch table
│   ├── UI.lua             # Dock widget interface
│   ├── PathResolver.lua   # Path notation resolver
│   ├── ValueSerializer.lua # JSON ↔ Roblox type converter
│   └── tools/             # 46 tool implementations
├── scripts/
│   └── bundle.js          # Plugin bundler script
└── dist/                  # Build output
    ├── server.js          # Compiled daemon
    ├── mcp.js             # Compiled MCP server
    ├── RbxGenie.plugin.lua # Bundled plugin
    └── RbxGenie.exe       # Standalone executable (optional)

Environment Variables

Optional environment variables:

Variable	Default	Description
`PORT`	`7766`	Daemon HTTP server port
`HOST`	`127.0.0.1`	Daemon bind address
`TIMEOUT`	`120000`	Command timeout in milliseconds

Set environment variables before starting the daemon:

export PORT=8080
npm run dev

If you change the port, you must also update the plugin’s HTTP endpoint in plugin/Bridge.lua.

Updating RbxGenie

To update to the latest version:

Pull latest changes

git pull origin main

Update dependencies

npm install

Rebuild and reinstall

npm run build
npm run bundle:install

Restart daemon and Studio

Stop the daemon (Ctrl+C)
Restart with npm run dev
Restart Roblox Studio to load the new plugin

Uninstallation

To remove RbxGenie:

Stop the daemon

Press Ctrl+C in the daemon terminal.

Remove the plugin

Delete RbxGenie.lua from your Roblox Plugins folder:

Windows: %LOCALAPPDATA%\Roblox\Plugins\RbxGenie.lua
macOS: ~/Documents/Roblox/Plugins/RbxGenie.lua

Remove MCP configuration (optional)

Edit Claude Desktop or Cursor MCP settings and remove the RbxGenie entry.

Delete the repository (optional)

rm -rf RbxGenie

Next Steps

Quickstart

Follow the quickstart guide to make your first tool call

MCP Integration

Learn how to use RbxGenie with Claude Desktop

Architecture

Understand how the daemon and plugin work together

Tools Reference

Explore all 46 available tools

Troubleshooting

npm install fails

Ensure Node.js 18+ is installed: node --version
Clear npm cache: npm cache clean --force
Delete node_modules and package-lock.json, then run npm install again
Check for network/proxy issues blocking npm registry access

TypeScript compilation errors

Ensure TypeScript is installed: npm install -g typescript
Check TypeScript version: tsc --version (should be 5.4.5 or compatible)
Try: npm run build -- --force

Plugin doesn't load in Studio

Verify the plugin file has a .lua extension
Check Roblox Studio Output window for error messages
Ensure the plugin was copied to the correct directory
Try manually opening the plugin in Studio’s Plugin Manager

MCP server not appearing in Claude

Verify dist/mcp.js exists (run npm run build)
Check that the path in claude_desktop_config.json is absolute and correct
Restart Claude Desktop completely
Check Claude’s logs: %APPDATA%/Claude/logs/mcp.log (Windows) or ~/Library/Logs/Claude/mcp.log (macOS)

BUILD.cmd fails on Windows

Common issues:

Node.js not in PATH: Add Node.js to your system PATH
npx command not found: Reinstall Node.js with npm included
Permission denied: Run as Administrator
TypeScript errors: Run npm install first to ensure all dependencies are installed

Get Started

Architecture

Integration

Guides

Examples

System Requirements

Node.js

Roblox Studio

Operating System

Git

Development Setup

Production Build

Daemon Executable

Plugin Installation

MCP Server Setup

Automatic Configuration

Manual MCP Configuration

Verify MCP Installation

Package.json Scripts Reference

File Structure

Environment Variables

Updating RbxGenie

Uninstallation

Next Steps

Quickstart

MCP Integration

Architecture

Tools Reference

Troubleshooting

Get Started

Architecture

Integration

Guides

Examples

Documentation Index

​System Requirements

Node.js

Roblox Studio

Operating System

Git

​Development Setup

​Production Build

​Daemon Executable

​Plugin Installation

​MCP Server Setup

​Automatic Configuration

​Manual MCP Configuration

​Verify MCP Installation

​Package.json Scripts Reference

​File Structure

​Environment Variables

​Updating RbxGenie

​Uninstallation

​Next Steps

Quickstart

MCP Integration

Architecture

Tools Reference

​Troubleshooting

System Requirements

Development Setup

Production Build

Daemon Executable

Plugin Installation

MCP Server Setup

Automatic Configuration

Manual MCP Configuration

Verify MCP Installation

Package.json Scripts Reference

File Structure

Environment Variables

Updating RbxGenie

Uninstallation

Next Steps

Troubleshooting