Roblox MCP v2.0

MCP server providing 12 tools for AI-driven Roblox Studio development.
Works with any MCP-compatible AI client (Cursor, Windsurf, Claude Code, Antigravity, etc.)

Quick Start

npm install

Add to your MCP config:

{
  "roblox-mcp": {
    "command": "node",
    "args": ["/path/to/roblox-mcp/index.js"]
  }
}

Copy RobloxMCPPlugin.server.luau to your Roblox Studio plugins folder:

%LOCALAPPDATA%/Roblox/Plugins/

Enable HttpService in Studio: Game Settings → Security → Allow HTTP Requests.

Tools

| Tool | Description | |------|-------------| | run_code | Execute arbitrary Luau in Studio | | take_screenshot | Capture Studio viewport (PrintWindow — no focus steal) | | get_descendants | Traverse instance tree (depth-limited) | | get_properties | Read instance properties | | find_instances | Search by ClassName / name pattern | | set_property | Set property via Luau expression | | create_instance | Create + parent + set properties | | delete_instance | Destroy with required confirm flag | | get_selection | Get currently selected instances | | move_camera | Position camera for screenshots | | get_output_log | Read LogService history | | get_health | Bridge diagnostics (instant, no Luau) |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | ROBLOX_MCP_PORT | 18820 | HTTP bridge port for plugin communication | | ROBLOX_MCP_SCREENSHOTS_DIR | ./screenshots (CWD) | Screenshot output directory |

Architecture

AI Agent ←stdio→ index.js (MCP + HTTP Bridge) ←HTTP→ RobloxMCPPlugin.server.luau

• Self-recovering bridge: 15s timeout auto-clears state, never permanently stuck
• Structured protocol: {success, result, error} with auto-serialized Roblox types
• PrintWindow screenshots: Captures without focus stealing (Windows only)
• Injection-safe: Value expressions use level-escalating long strings [=[...]=]

Requirements

• Node.js ≥ 18
• Roblox Studio (Windows)
• PowerShell (for take_screenshot)

License

MIT