roblox-bridge-mcp

AI-powered bridge connecting Model Context Protocol to Roblox Studio

Real-time control of Roblox Studio instances through a unified MCP interface. Build, script, and manipulate 3D worlds using AI assistants like Claude.

Getting Started • Installation • Usage • API Reference

Overview

roblox-bridge-mcp enables AI agents to directly interact with Roblox Studio through the Model Context Protocol. It provides 99 operations spanning instance management, scripting, physics, lighting, terrain, camera control, and more through a single unified tool.

Architecture:

MCP Server - FastMCP + Bun server exposing the roblox tool
HTTP Bridge - Local server with automatic port allocation (tries 8081-8090)
Studio Plugin - Lua plugin with automatic server discovery and connection

Features

Single Unified Tool - All 99 operations accessible via one roblox tool with method dispatch
API Key Security - Simple authentication to protect the bridge server
Automatic Port Discovery - Bridge server tries ports 8081-8090 with automatic fallback
Long-Polling & WebSocket - Near-instant command delivery (replaces 300ms polling)
Seamless Startup - MCP server always starts, even if bridge port is occupied
Real-time Communication - HTTP long-polling with exponential backoff reconnection
Studio Integration - Toolbar button with visual connection indicator and auto-discovery
Comprehensive Coverage - Instance CRUD, scripting, transforms, physics, terrain, camera, and more
Type-Safe - Zod schemas for all parameters
Modern Stack - Bun runtime, FastMCP framework, task-based Lua

Getting Started

Prerequisites

Roblox Studio
An MCP client (Claude Desktop, etc.)

Installation

1. Configure your MCP client

Add to your MCP client configuration (e.g., Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "roblox-bridge": {
      "command": "npx",
      "args": ["-y", "roblox-bridge-mcp"]
    }
  }
}

2. Install the Studio plugin

Download the latest plugin from the releases page.

Create a folder in your Roblox plugins directory:

Windows: %LOCALAPPDATA%\Roblox\Plugins\Roblox Bridge MCP\
macOS: ~/Documents/Roblox/Plugins/Roblox Bridge MCP/

Place the plugin file as init.server.lua inside this folder.

3. Configure the API key

When the MCP server starts, it displays an API key in the console:

[Bridge] Roblox bridge server running on port 8081
[Bridge] API Key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
[Bridge] Set this key in your Roblox plugin to connect

In Roblox Studio, open the command bar (View > Command Bar) and run:

_G.MCP_SetApiKey("a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6")

The key is saved in plugin settings and persists across Studio sessions.

Tip: For a persistent API key that survives server restarts, set ROBLOX_API_KEY in your environment (see Configuration).

4. Start Roblox Studio

Open a place in Studio. The plugin will auto-connect (toolbar button turns active).

5. Use from your MCP client

The roblox tool will be available in your MCP client (restart the client if needed).

Configuration

Environment Variables

You can configure the bridge server behavior using environment variables. Create a .env file in your project root or set these in your MCP client configuration:

Variable	Description	Default
`ROBLOX_API_KEY`	API key for bridge authentication (auto-generated if not set)	Random UUID
`ROBLOX_BRIDGE_PORT`	Preferred port for the HTTP bridge server (will try 8081-8090)	`8081`
`ROBLOX_TIMEOUT_MS`	Timeout in milliseconds for command execution	`30000`
`ROBLOX_RETRIES`	Number of retry attempts for failed commands	`2`
`LOG_LEVEL`	Logging level (DEBUG, INFO, WARN, ERROR)	`INFO`

Note: If ROBLOX_API_KEY is not set, a random key is generated on each server startup. For persistent connections, set a fixed key in your .env file.

Note: The bridge server automatically tries ports 8081-8090 in sequence. If the preferred port is occupied, it will use the next available port. The Studio plugin automatically discovers and connects to the active server.

Example .env file:

# Persistent API key (recommended for production)
ROBLOX_API_KEY=my-secure-api-key-here

ROBLOX_BRIDGE_PORT=8081
ROBLOX_TIMEOUT_MS=30000
ROBLOX_RETRIES=2
LOG_LEVEL=INFO

MCP Client Configuration:

{
  "mcpServers": {
    "roblox-bridge-mcp": {
      "command": "npx",
      "args": ["-y", "roblox-bridge-mcp"],
      "env": {
        "ROBLOX_API_KEY": "my-secure-api-key-here",
        "ROBLOX_BRIDGE_PORT": "8081",
        "LOG_LEVEL": "INFO",
        "ROBLOX_RETRIES": "2",
        "ROBLOX_TIMEOUT_MS": "30000"
      }
    }
  }
}

Usage

Basic Workflow

Open Roblox Studio with a place
The plugin will auto-connect (toolbar button turns active)
Use your MCP client to call the roblox tool

Example Commands

Create a part:

{
  "method": "CreateInstance",
  "params": {
    "className": "Part",
    "parentPath": "game.Workspace",
    "name": "MyPart",
    "properties": {
      "Anchored": true,
      "Size": [4, 1, 4]
    }
  }
}

Set color:

{
  "method": "SetColor",
  "params": {
    "path": "game.Workspace.MyPart",
    "r": 255,
    "g": 0,
    "b": 0
  }
}

Create a script:

{
  "method": "CreateScript",
  "params": {
    "name": "HelloWorld",
    "parentPath": "game.Workspace",
    "source": "print('Hello from AI!')",
    "type": "Script"
  }
}

Get selection:

{
  "method": "GetSelection",
  "params": {}
}

API Reference

The `roblox` Tool

All operations are accessed through a single tool with two parameters:

method (string) - The operation to execute (see methods below)
params (object) - Method-specific parameters

Available Methods (click to expand)

Instance Management

CreateInstance(className, parentPath, name?, properties?) - Create a new instance
DeleteInstance(path) - Destroy an instance
CloneInstance(path, parentPath?) - Clone an instance
RenameInstance(path, newName) - Rename an instance

Property Access

SetProperty(path, property, value) - Set a property value
GetProperty(path, property) - Get a property value

Hierarchy Navigation

GetChildren(path) - Get child names
GetDescendants(path) - Get all descendant paths
FindFirstChild(path, name, recursive?) - Find a child by name
GetService(service) - Get a Roblox service

Transform

MoveTo(path, position[x,y,z]) - Move a Model or BasePart
SetPosition(path, x, y, z) - Set Position property
SetRotation(path, x, y, z) - Set Rotation (degrees)
SetSize(path, x, y, z) - Set Size property
PivotTo(path, cframe[12]) - Set CFrame via PivotTo
GetPivot(path) - Get CFrame as 12 components

Appearance

SetColor(path, r, g, b) - Set Color3 (0-255 RGB)
SetTransparency(path, value) - Set Transparency (0-1)
SetMaterial(path, material) - Set Material enum

Physics

SetAnchored(path, anchored) - Set Anchored property
SetCanCollide(path, canCollide) - Set CanCollide property

Scripting

CreateScript(name, parentPath, source, type?) - Create a script with source code
GetScriptSource(path) - Read script source
SetScriptSource(path, source) - Replace script source
AppendToScript(path, code) - Append to script
ReplaceScriptLines(path, startLine, endLine, content) - Replace line range
InsertScriptLines(path, lineNumber, content) - Insert lines at position
RunConsoleCommand(code) - Execute Luau code in command bar context

Selection

GetSelection() - Get currently selected objects
SetSelection(paths[]) - Set selection to specific objects
ClearSelection() - Clear selection
AddToSelection(paths[]) - Add to current selection

Grouping

GroupSelection(name) - Group selected objects into Model
UngroupModel(path) - Ungroup a Model

Lighting

SetTimeOfDay(time) - Set Lighting.TimeOfDay (e.g., "14:00:00")
SetBrightness(brightness) - Set Lighting.Brightness
SetAtmosphereDensity(density) - Set Atmosphere.Density (creates if missing)
CreateLight(parentPath, type, brightness?, color?) - Create a light object

Attributes & Tags

SetAttribute(path, name, value) - Set an attribute
GetAttribute(path, name) - Get an attribute value
GetAttributes(path) - Get all attributes
AddTag(path, tag) - Add a CollectionService tag
RemoveTag(path, tag) - Remove a tag
GetTags(path) - Get all tags
HasTag(path, tag) - Check if instance has tag

Players

GetPlayers() - Get list of player names
GetPlayerPosition(username) - Get player character position
TeleportPlayer(username, position[x,y,z]) - Teleport player
KickPlayer(username, reason?) - Kick player from game

Place/Studio

SavePlace() - Trigger save (if permissions allow)
GetPlaceInfo() - Get PlaceId, Name, JobId

Audio

PlaySound(soundId, parentPath?, volume?) - Create and play a sound
StopSound(path) - Stop a playing sound

Utility

GetDistance(path1, path2) - Calculate distance between two objects
HighlightObject(path, color?, duration?) - Add visual Highlight
Chat(message, color?) - Send system message to TextChatService

Path Format

All instance paths use dot notation starting from game:

game.Workspace.Model.Part
game.ReplicatedStorage.Assets
Service names are automatically resolved: game.Workspace resolves to Workspace service

Plugin Features

The Studio plugin provides:

API Key Authentication - Secure connection with server-provided key
Automatic Discovery - Scans ports 8081-8090 to find and connect to the bridge server
Service Validation - Verifies server identity using health endpoint before connecting
Long-Polling - Near-instant command delivery (no 300ms polling delay)
Toolbar Integration - "MCP Bridge" toolbar with toggle button
Connection Status - Visual indicator (active = connected, inactive = disconnected)
Enable/Disable - Click toolbar button to toggle bridge on/off
Auto-Reconnect - Exponential backoff (2s to 10s) on connection loss with port rediscovery
Persistent Settings - API key saved across Studio sessions
Modern Lua - Uses task library, no deprecated APIs
Error Handling - Structured error messages with context

Plugin Commands

Run these in the Studio command bar (View > Command Bar):

-- Set API key (required for first connection)
_G.MCP_SetApiKey("your-api-key-here")

-- Check current API key (shows truncated key)
print(_G.MCP_GetApiKey())

Architecture

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   MCP Client    │ stdio   │   FastMCP Server │  HTTP   │  Studio Plugin  │
│  (Claude, etc)  │◄───────►│   (Bun + Node)   │◄───────►│   (Lua/Luau)    │
└─────────────────┘         └──────────────────┘         └─────────────────┘
                                     │                            │
                                     │                            │
                                ports 8081-8090              Roblox API
                         /health, /poll, /result      (game.Workspace, etc)

Communication Flow:

Bridge server starts on first available port (8081-8090)
Plugin discovers server by scanning ports and validating /health endpoint
MCP client calls roblox tool with method + params
Server adds command to queue
Plugin polls /poll, receives commands
Plugin executes command in Studio using Roblox API
Plugin posts result to /result
Server resolves promise, returns to MCP client

Development

For contributors or those running from source:

Clone and install:

git clone https://github.com/CoderDayton/roblox-bridge-mcp.git
cd roblox-bridge-mcp
bun install

Run in development mode:

bun run dev

Run tests:

bun test                  # Run all tests
bun test --watch          # Watch mode
bun test --coverage       # With coverage report

Code quality:

bun run typecheck         # TypeScript type checking
bun run lint              # ESLint strict mode
bun run lint:fix          # Auto-fix linting issues
bun run format            # Format with Prettier

Inspect MCP server:

bun run inspect

Build for production:

bun run build

Code Quality Standards

This project maintains high code quality standards:

Documentation: Comprehensive JSDoc comments on all exported functions
Type Safety: TypeScript strict mode with explicit return types
Testing: 87%+ test pass rate with comprehensive coverage
Linting: ESLint strict ruleset enforcing best practices
Formatting: Prettier for consistent code style

See CONTRIBUTING.md for detailed development guidelines.

Troubleshooting

Plugin says "API key not set":

Run _G.MCP_SetApiKey("your-key") in the Studio command bar
The API key is shown in the server console when it starts
If using a persistent key, ensure ROBLOX_API_KEY is set in your environment

Plugin not connecting:

Check that Roblox Studio is running
Verify HttpService is enabled in Studio settings (Game Settings > Security)
Ensure no firewall is blocking localhost ports 8081-8090
Check Studio output window for [MCP] log messages showing port discovery
The plugin will show which port it discovered (e.g., "Discovered server on port 8084")
Verify the API key is correct (check server console output)

Tool not appearing in MCP client:

Verify MCP client configuration points to correct path
Restart MCP client after configuration changes
Check that bun run dev is running without errors
The MCP server will always start even if the bridge port is occupied

Commands timing out:

Default timeout is 30 seconds
Check Studio output for Lua errors
Verify instance paths are correct (use GetChildren to explore)

Port conflicts:

The bridge automatically tries ports 8081-8090
Check server startup logs to see which port was used
If all ports are occupied, the MCP server will still start but tools will fail until a port is available

401 Unauthorized errors:

The API key in the plugin doesn't match the server's key
Re-copy the key from the server console and set it with _G.MCP_SetApiKey()
If using ROBLOX_API_KEY env var, ensure it's the same on both ends

Contributing

Contributions are welcome! Please read our Contributing Guide for guidelines on:

Setting up the development environment
Code standards and testing requirements
Pull request process
Adding new Roblox tools

For major changes, please open an issue first to discuss your proposal.

License

MIT License - see LICENSE file for details

Acknowledgments

Built with FastMCP
Powered by Bun
Inspired by the Model Context Protocol specification

Roblox Bridge MCP