The Roblox MCP server acts as a real-time bridge between AI coding agents and Roblox Studio, enabling direct creation, modification, and management of game content via natural language.
Instance Management: Create, delete, clone, move, rename, and pivot instances; query by name, class, property, or tag; traverse hierarchy; perform mass operations and create instance trees
Property & Attribute Control: Get/set properties, attributes, and tags; bulk/mass operations; calculated or relative property changes
Script Management: Read/write source code, create/delete scripts, edit by line number, find/replace across scripts, get dependencies
Lighting & Environment: Configure Lighting service, Atmosphere, Sky, terrain visual properties, and time of day
Selection Control: Get, set, clear, add to, or remove from Studio selection; watch for selection changes
Camera Control: Get camera info, focus on instances or world positions, get suggested views
Animation & Tweening: Load, play, and stop animations on Humanoids/AnimationControllers; create, play, pause, and cancel smooth property tweens
Audio Management: Play, stop, pause, and resume sounds; set audio listener type
Particle Effects: Emit particle bursts, clear particles, toggle effects on/off
Physics: Register collision groups and configure collision rules between them
Terrain Generation & Editing: Fill shapes (block/ball/cylinder/wedge), clear regions, replace materials, read/write voxels, generate procedural terrain, smooth terrain
Spatial Queries: Raycasting, ground detection, placement validation, area scanning, flat surface finding, walkability analysis, collision checking, spatial mapping, grid snapping
Asset Management: Insert models by asset ID, search the Creator Store, insert free models/packages, export selections
Project Sync: Bidirectional sync between Studio and local files; manage config, history, and per-type sync directions; read/write synced files
Workspace State: Full workspace snapshots, recent changes, viewport info, script lists, and selection details
Playtest Automation: Start, stop, pause, and resume playtests; inject test scripts, collect logs, generate automated test reports
Log Management: Retrieve and filter logs, poll incrementally, clear log buffer, get recent errors
System Info: Connection/ping status, place info, Studio settings, service lists
Batch Execution: Run multiple tool commands sequentially in a single request
Luau Code Execution: Run arbitrary Luau code directly inside a sandboxed Roblox Studio environment
Dashboard & VSCode Integration: Real-time web dashboard for monitoring connection, tool history, and sync state; view Studio instance hierarchy in VSCode
Enables AI-powered game development on the Roblox platform, including asset integration from the Creator Store, project synchronization, and automated playtesting.
Connects AI agents to a live Roblox Studio session, enabling them to directly create, read, modify, and delete instances, scripts, properties, and terrain via natural language.
Roblox MCP — MCP Server for Roblox Studio | AI Game Development with Claude, Codex, Cursor & Gemini
Weppy Roblox MCP is an MCP server that lets AI coding agents control a live Roblox Studio session — create and edit scripts, instances, terrain, lighting, assets, audio, and animations via natural language.
21 consolidated tools · 140+ actions · Bidirectional sync · Automated playtest · Multi-place support
English | 한국어 | 日本語 | Español | Português | Bahasa Indonesia
Why Weppy Roblox MCP?
AI coding agents like Claude, Codex, and Gemini are powerful — but they cannot see or modify anything inside Roblox Studio. The DataModel, scripts, terrain, and lighting are all invisible to external tools. Without a bridge, AI can only generate code snippets that you must paste manually.
Weppy Roblox MCP provides a real-time bridge between AI agents and the Roblox Studio DataModel. It exposes the full Roblox API surface as executable MCP tools, so AI can directly create, read, modify, and delete instances, scripts, properties, terrain, and more — inside a live Studio session.
This is not just code generation. It is executable, production-oriented actions running directly in Studio.
Quick Install
One-line install — installs the MCP server, Roblox Studio plugin, and registers with your AI apps:
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.sh | bashWindows (PowerShell)
irm https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.ps1 | iexThen restart Roblox Studio — done!
Automatic MCP registration currently supports Claude Code, Claude Desktop, Cursor, Codex CLI, and Gemini CLI. Codex App and Antigravity still require manual setup after the script finishes.
If PowerShell execution is blocked on Windows, use the manual install path below. If you're using the ZIP package, you can also use setup-plugin.bat and setup-mcp.bat.
Manual Install
If the one-line install does not work, or automatic installation is not available in your environment, use the manual install path below.
Step 1 — Install the Roblox Studio plugin (bridge between Studio and AI): Plugin Installation Guide
Step 2 — Register the MCP server with your AI app:
npx -y @weppy/roblox-mcpAI App | Guide |
Claude Code | |
Claude Desktop | |
Cursor | |
Codex CLI | |
Codex Desktop | |
Gemini CLI | |
Antigravity |
Any MCP-compatible AI client works. The server command is
npx -y @weppy/roblox-mcp.
Compatibility
Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI | Antigravity |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Requirements: Node.js 18+, Roblox Studio, Windows 10+ or macOS 12+
What It Does
1) MCP Tools: Direct execution in Studio from natural language
AI can directly handle scripts, instances, properties, terrain, lighting, assets, audio, and animation inside Studio.
"Add particles + sound + cooldown when the player jumps."
"Build a boss arena at map center and place collision-safe spawn points."
"Change this module interface and update every dependent script."
"Generate terrain with mountains and rivers, then place spawn points on flat areas."
"Search the Creator Store for a sword model and insert it into StarterPack."
2) Sync: Keep full project context stable for AI
AI works from a synchronized local mirror, so multi-file updates stay consistent.
Basic: one-way sync (Studio -> Local)
Pro: bidirectional sync + per-type Direction/Apply Mode + history + multi-place
3) Playtest: Let AI run and verify tests automatically
AI can control Roblox Studio playtests directly. It can start and stop Play (F5) or Run (F8), inject test scripts, collect logs, and generate local reports automatically.
"Start a Run-mode playtest and check whether the NPC reaches the target."
"Write a test that verifies the SpawnLocation is above the ground and run it."
"Validate that the script I just changed runs without errors in playtest."
4) Dashboard: Monitor AI work in real time
The MCP server provides a web dashboard where you can check connection status, tool execution history, sync state, and game change logs in real time.
Server/Plugin/Agent connection status at a glance
Compare every change the AI made via Before & After in Changelog
Analyze workflow with tool execution history and statistics
5) Roblox Explorer: Browse Studio hierarchy in VSCode
View the full instance tree of your Roblox Studio place directly inside VSCode. Navigate services, open synced scripts and property files, and track sync status — all without switching to Studio.
Class icons matching Studio for instant recognition
Click to open synced scripts and property files
Multi-place support with sync status indicators
Use Cases
Rapid prototyping: Describe a game mechanic in natural language and watch AI build it in Studio
Bulk refactoring: Rename a module interface and update every dependent script in one request
Terrain & environment: Generate procedural terrain, set lighting/atmosphere, place assets — all from a single prompt
Multi-file consistency: AI reads the full project via Sync and applies changes across related scripts together
Asset integration: Search the Creator Store, insert models, and configure properties without leaving your editor
Why It Matters
Compress repetitive work: turn many manual edits into one request
Change related files together: not just one target file
Lower risk: rely on sync state and history before applying changes
Better token efficiency (Pro): reduce round trips with bulk actions
Docs
Workflow Guides
Instances & Properties - search, creation, editing, tags
Scripting & Code Execution - script management and Luau execution
World & Environment - lighting, terrain, camera
Assets & Effects - asset insertion, tweening, effects
Playtest & Automated Tests - playtest control and automated validation
System & Debugging - connection, logs, batch execution
FAQ
How do I connect Claude Code to Roblox Studio?
Install the Roblox Studio plugin, then register the MCP server (npx -y @weppy/roblox-mcp) in Claude Code. Claude can then directly read and write scripts inside Studio. See Claude Code Setup.
How do I use Codex CLI with Roblox Studio?
Install the plugin, then add the MCP server config to Codex CLI. See Codex CLI Setup.
Does Roblox MCP work with Cursor?
Yes. See Cursor Setup. Any MCP-compatible AI client works.
Can AI build Roblox games with this?
Yes. AI can create instances, write scripts, generate terrain, set up lighting, insert assets, configure physics, and more — all inside a live Roblox Studio session. It goes beyond code generation to executable actions.
What is the difference between Basic and Pro?
Basic (Free) includes MCP tool execution and one-way sync (Studio -> Local). Pro adds bidirectional sync, bulk operations, terrain generation, spatial analysis, audio/animation control, and multi-place support. See the Pro Upgrade Guide.
How is Weppy different from other Roblox MCP servers?
Weppy uses 21 consolidated tools with action-based dispatching (140+ actions) instead of separate tools for each function. This reduces AI token consumption significantly. It also provides bidirectional project sync and multi-place support, which most alternatives lack.
Is it safe? Can AI break my game?
The server runs on localhost only (127.0.0.1:3002). Forbidden paths (CoreGui, CorePackages) are blocked. Rate limiting (450 req/min) and 30-second timeouts prevent runaway operations. All changes are trackable via sync history.
Pro Upgrade
Bidirectional Sync, advanced build capabilities, and AI token efficiency — all in one upgrade.
License
This repository is licensed under AGPL-3.0.
Commercial licensing is available separately. See COMMERCIAL-LICENSE.md.
Use of the Weppy name and logos is governed by TRADEMARKS.md.
