Installation Guide

Complete installation guide for both the MCP server and Roblox Studio plugin.

System Requirements

Node.js 16.x or higher (for MCP server)
Roblox Studio (latest version recommended)
MCP-compatible AI client (Claude Code, Claude Desktop, or any MCP client)
Operating System: Windows, macOS, or Linux

Part 1: MCP Server Installation

The MCP server runs on your machine and exposes tools to AI assistants.

Option A: Install via NPM (Recommended)

Install the package globally or in your project:

npm install -g robloxstudio-mcp

Or install locally in your project:

npm install robloxstudio-mcp

Option B: Run with npx (No Installation)

The npx method downloads and runs the latest version automatically:

npx -y robloxstudio-mcp

This is the recommended approach for MCP client configurations.

Part 2: MCP Client Configuration

Configure your AI client to use the Roblox Studio MCP server.

Claude Code
Claude Desktop
Other MCP Clients

Claude Code Setup

Claude Code has built-in MCP support. Add the server with:

claude mcp add robloxstudio -- npx -y robloxstudio-mcp

This command:

Adds “robloxstudio” to your MCP configuration
Configures it to run via npx -y robloxstudio-mcp
Makes tools available immediately

Verify installation:

claude mcp list

You should see “robloxstudio-mcp” in the list.Remove if needed:

claude mcp remove robloxstudio

Claude Desktop Setup

Locate your configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json
Add the MCP server configuration:

{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "npx",
      "args": ["-y", "robloxstudio-mcp"],
      "description": "Advanced Roblox Studio integration for AI assistants"
    }
  }
}

Restart Claude Desktop for changes to take effect.

If you have other MCP servers configured, add “robloxstudio-mcp” to the existing “mcpServers” object.

Generic MCP Client Setup

For other MCP-compatible clients, add this configuration to your MCP config file:

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

Consult your AI client’s documentation for the config file location.

Windows-Specific Configuration

If you’re on native Windows (not WSL) and encounter issues, use this configuration:

{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "robloxstudio-mcp@latest"]
    }
  }
}

This runs the command through cmd.exe which can resolve path and environment issues.

Part 3: Studio Plugin Installation

The plugin runs inside Roblox Studio and executes API calls for the MCP server.

Choose Installation Method

Select the method that works best for you:

Method 1: Roblox Creator Store (Easiest)

Visit: https://create.roblox.com/store/asset/132985143757536
Click the “Install” button
Plugin opens automatically in Studio
No restart needed — ready to use immediately!

Method 2: Direct Download

Download the plugin file:
- MCPPlugin.rbxmx
Save to plugins folder:
- Windows: %LOCALAPPDATA%/Roblox/Plugins/
  - Full path: C:\Users\YourName\AppData\Local\Roblox\Plugins\
- macOS: ~/Documents/Roblox/Plugins/
  - Full path: /Users/YourName/Documents/Roblox/Plugins/
- Or use Studio: Plugins tab → Plugins Folder button
Restart Roblox Studio completely
Plugin appears in toolbar with “MCP Server” button

Method 3: Save as Local Plugin

Copy the plugin source code:
- Open plugin.luau on GitHub
- Select all code (Ctrl+A / Cmd+A) and copy (Ctrl+C / Cmd+C)
Create in Studio:
- Open any Roblox Studio place
- In Explorer, right-click ServerScriptService
- Click “Insert Object” → “Script”
- Paste the plugin code into the script
Save as plugin:
- Right-click the script
- Select “Save as Local Plugin…”
- Name it “Roblox Studio MCP”
- Click Save
Plugin appears immediately in your toolbar — no restart needed!

Enable HTTP Requests

The plugin requires HTTP access to communicate with the MCP server on localhost:3002.

In Roblox Studio, click Home tab
Click Game Settings button
Navigate to Security section
Find “Allow HTTP Requests” and check the box
Click OK to save

Critical: Without this setting, the plugin cannot connect. You’ll see “HTTP 403 Forbidden” errors in the Output window.

Alternative method:Insert a Script and run this code once:

game:GetService("HttpService").HttpEnabled = true

Then delete the script.

Activate the Plugin

Look for the “MCP Server” button in the Plugins toolbar
Click the button to activate
A dock widget appears with:
- Connection status indicator
- Activity log panel
- Server URL configuration (default: http://localhost:3002)

The plugin starts in disconnected state (🔴 red). This is normal. It connects automatically when your AI makes requests.

Verify Installation

Test that everything works:

Check plugin status:
- Plugin button should be in toolbar
- Dock widget should be visible
- No errors in Output window
Test with AI:
- Open your AI assistant (Claude Code/Desktop)
- Ask: “Show me the services in my Roblox game”
- AI should call get_services tool
- Plugin status changes to 🟢 “Connected”
- AI returns formatted list of services
Check activity log:
- Plugin’s activity panel shows the request
- You can copy/export the log

If everything works, you’re ready to go! 🎉

Configuration

Environment Variables

The MCP server supports these environment variables:

# HTTP bridge port (default: 3002)
HTTP_SERVER_PORT=3002

# Request timeout in milliseconds (default: 30000)
REQUEST_TIMEOUT=30000

# Plugin poll interval in milliseconds (default: 500)
PLUGIN_POLL_INTERVAL=500

Set these in your shell or MCP client configuration:

{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "npx",
      "args": ["-y", "robloxstudio-mcp"],
      "env": {
        "HTTP_SERVER_PORT": "3002",
        "REQUEST_TIMEOUT": "30000"
      }
    }
  }
}

Plugin Configuration

The plugin uses these defaults:

Server URL: http://localhost:3002
Poll Interval: 500ms (with long polling)
Timeout: 30 seconds per request

You can modify the server URL in the plugin’s dock widget if needed (e.g., different port or network testing).

Troubleshooting

MCP Server Issues

'npx: command not found'

Node.js isn’t installed or not in your PATH.Solution:

Install Node.js from nodejs.org
Verify: node --version and npm --version
Restart your terminal
Try the MCP installation again

'Permission denied' errors

NPM packages can’t install globally without permissions.Solution (macOS/Linux):

sudo npm install -g robloxstudio-mcp

Solution (Windows):

Run terminal as Administrator
Or use npx method instead (no installation needed)

AI can't find the tools

MCP server isn’t running or misconfigured.Checklist:

Configuration file has correct JSON syntax
You restarted your AI client after editing config
For Claude Code: claude mcp list shows the server
No firewall blocking localhost:3002

Server crashes or times out

Network or port conflicts.Solution:

Check if port 3002 is in use: netstat -an | grep 3002 (Unix) or netstat -an | findstr 3002 (Windows)
Change port via environment variable:
```
"env": { "HTTP_SERVER_PORT": "3003" }
```
Update plugin URL to match new port

Studio Plugin Issues

Plugin missing from toolbar

'HTTP 403 Forbidden' errors

HTTP requests are disabled in game settings.Solution:

Game Settings → Security → Enable “Allow HTTP Requests”
Click OK and close settings
If error persists, restart Studio
Run this script once: game:GetService("HttpService").HttpEnabled = true

Plugin shows 'Disconnected' always

This is normal behavior when idle. The plugin only connects when handling requests.To test:

Ask your AI: “Get game.Workspace structure”
Watch plugin status change to 🟢 “Connected”
After request completes, returns to “Disconnected”

If it never connects:

MCP server isn’t running (check AI client)
Firewall blocking localhost:3002
Wrong server URL in plugin settings

'Connection refused' or timeout errors

Plugin can’t reach MCP server.Solution:

Verify MCP server is running (ask AI a question)
Check plugin server URL matches MCP server port (default: http://localhost:3002)
Windows Firewall: Allow localhost connections
Antivirus: Whitelist Node.js and Roblox Studio

Plugin works but requests are slow

Network latency or polling issues.Solution:

Check Output window for retry/timeout messages
Long polling should respond instantly; 500ms+ delay suggests issues
Verify no VPN or proxy intercepting localhost traffic
Try restarting both Studio and MCP server

General Issues

Results are incomplete or truncated

Large responses may need pagination or depth limits.Solution:

Use maxDepth parameter on get_project_structure (try 5-10)
For large scripts, use startLine/endLine parameters
Check Output window for memory/size warnings

AI hallucinating tool parameters

AI isn’t using the correct tool schema.Solution:

Be specific: “Use maxDepth=5” instead of “show me everything”
For paths: Always use dot notation like game.Workspace.Part
For Vector3: Use {X: 0, Y: 5, Z: 0} format, not strings
Check AI client has latest MCP server version

Updating

Update MCP Server

For npx method:

npx -y robloxstudio-mcp@latest

For npm global install:

npm update -g robloxstudio-mcp

For npm local install:

npm update robloxstudio-mcp

Update Studio Plugin

Download latest MCPPlugin.rbxmx
Replace existing file in plugins folder
Restart Studio

Or re-install from Creator Store (auto-updates).

Next Steps

Quick Start

Try your first AI commands

Tool Reference

Explore all 53+ tools

Getting Help

If you’re still stuck:

GitHub Issues: Report bugs
Discussions: Ask questions
Check Output Window: Studio’s Output tab shows detailed error messages
Activity Log: Plugin’s activity panel tracks all requests

Get Started

Core Concepts

Plugin Setup

Development

Installation

Installation Guide

System Requirements

Part 1: MCP Server Installation

Option A: Install via NPM (Recommended)

Option B: Run with npx (No Installation)

Part 2: MCP Client Configuration

Claude Code Setup

Claude Desktop Setup

Generic MCP Client Setup

Windows-Specific Configuration

Part 3: Studio Plugin Installation

Method 1: Roblox Creator Store (Easiest)

Method 2: Direct Download

Method 3: Save as Local Plugin

Configuration

Environment Variables

Plugin Configuration

Troubleshooting

MCP Server Issues

Studio Plugin Issues

General Issues

Updating

Update MCP Server

Update Studio Plugin

Next Steps

Quick Start

Tool Reference

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Concepts

Plugin Setup

Development

​Installation Guide

​System Requirements

​Part 1: MCP Server Installation

​Option A: Install via NPM (Recommended)

​Option B: Run with npx (No Installation)

​Part 2: MCP Client Configuration

​Claude Code Setup

​Claude Desktop Setup

​Generic MCP Client Setup

​Windows-Specific Configuration

​Part 3: Studio Plugin Installation

​Method 1: Roblox Creator Store (Easiest)

​Method 2: Direct Download

​Method 3: Save as Local Plugin

​Configuration

​Environment Variables

​Plugin Configuration

​Troubleshooting

​MCP Server Issues

​Studio Plugin Issues

​General Issues

​Updating

​Update MCP Server

​Update Studio Plugin

​Next Steps

Quick Start

Tool Reference

​Getting Help

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Part 1: MCP Server Installation

Option A: Install via NPM (Recommended)

Option B: Run with npx (No Installation)

Part 2: MCP Client Configuration

Claude Code Setup

Claude Desktop Setup

Generic MCP Client Setup

Windows-Specific Configuration

Part 3: Studio Plugin Installation

Method 1: Roblox Creator Store (Easiest)

Method 2: Direct Download

Method 3: Save as Local Plugin

Configuration

Environment Variables

Plugin Configuration

Troubleshooting

MCP Server Issues

Studio Plugin Issues

General Issues

Updating

Update MCP Server

Update Studio Plugin

Next Steps

Getting Help