A step-by-step guide for narrowing down connection, permission, Sync, and validation issues.
Plugin Not Connecting
Symptom: “Connection failed” or the plugin shows as disconnected in Roblox Studio.
- Confirm the MCP server is running:
npx -y @weppy/roblox-mcp - Roblox Studio: Plugins tab → WEPPY → click Connect
- Make sure no firewall, antivirus, or VPN is blocking
localhost:3002 - Restart both Roblox Studio and the MCP server
AI Client Not Recognizing the MCP Server
- Check that the correct command is used in AI client settings:
npx -y @weppy/roblox-mcp - Confirm Node.js 18 or higher is installed:
node --version - On Windows, if you get a permissions error, try running the terminal as Administrator
- Check the installation guide for your AI app
”Pro feature required” Notice
When a Pro-only action is requested on Basic, WEPPY tries to find a workaround where possible. However, the workaround flow consumes additional tokens and doesn’t always produce identical results.
Some Pro-only tools also have no feasible workaround and cannot be executed on Basic at all. If this notice appears repeatedly, consider upgrading to Pro.
Sync Not Working
- Check Sync status: ask the AI to run
manage_sync status - Confirm the plugin is connected before starting Sync
- If reverse sync (file → Studio) isn’t working, verify that Pro tier is active
- Confirm the local sync folder exists and has write permissions
See Bidirectional Sync for detailed Sync configuration.
Compatible AI Clients
| Client | Basic | Pro |
|---|---|---|
| Claude Code | ✅ | ✅ |
| Claude Desktop | ✅ | ✅ |
| Cursor | ✅ | ✅ |
| Codex CLI | ✅ | ✅ |
| Codex Desktop | ✅ | ✅ |
| Gemini CLI | ✅ | ✅ |
| Any MCP-compatible app | ✅ | ✅ |
Server command: npx -y @weppy/roblox-mcp
System Requirements
| Item | Minimum |
|---|---|
| Node.js | 18.0.0 or higher |
| Roblox Studio | Latest version (keep auto-update enabled) |
| Operating System | Windows 10+ or macOS 12+ |
| Network | localhost:3002 must be accessible |
Basic vs Pro Feature Comparison
Basic (free) covers the core AI coding workflow. It includes all the essential tools for instances, properties, scripts, selection, camera, and logs, plus Studio → Local one-way Sync and tool execution history. Pro adds bidirectional Sync, bulk operations, and an advanced tool suite covering terrain, lighting, physics, audio, and animations.
| Feature | Basic | Pro |
|---|---|---|
| Search, create, delete, clone, and move instances | ✅ | ✅ |
| Instance tree and hierarchy navigation | ✅ | ✅ |
| Read/write properties and tags | ✅ | ✅ |
| Read, write, and edit scripts | ✅ | ✅ |
| Selection management | ✅ | ✅ |
| Camera movement and focus | ✅ | ✅ |
| Log viewing | ✅ | ✅ |
| System info and connection check | ✅ | ✅ |
| Tool execution history and statistics | ✅ | ✅ |
| Studio → Local one-way Sync | ✅ | ✅ |
| Bidirectional Sync (Local → Studio) | — | ✅ |
| Per-type Direction / Apply Mode | — | ✅ |
| Sync change history | — | ✅ |
| Multi-place sync (up to 3) | — | ✅ |
| Bulk operations (batch create/edit) | — | ✅ |
| Lighting and atmosphere control | — | ✅ |
| Terrain generation and editing | — | ✅ |
| Tween and animation control | — | ✅ |
| Audio control | — | ✅ |
| Particles and effects | — | ✅ |
| Physics groups and collision | — | ✅ |
| Spatial queries and raycasting | — | ✅ |
| Asset search, insertion, and export | — | ✅ |
| Screenshot capture | — | ✅ |
| Automated playtest and test injection | — | ✅ |
| Batch execution and arbitrary Luau code | — | ✅ |
When a Basic user requests a Pro-only feature, WEPPY finds a workaround where possible, but this consumes more tokens and some features cannot be worked around at all. See the “Pro feature required” Notice section above for details.
Common Error Messages
| Error | Cause | Fix |
|---|---|---|
ECONNREFUSED localhost:3002 | MCP server not running | Run npx -y @weppy/roblox-mcp |
Timeout waiting for plugin | Studio plugin not connected | Click Connect in the plugin panel |
Forbidden path | Attempted access to CoreGui/CorePackages | Use only valid instance paths |
Place ID mismatch | Wrong Place connected | Reconnect from the correct Studio session |
Need Help?
If the issue still isn’t resolved, post in GitHub Discussions with the following information:
- Operating system and Node.js version
- AI client and version
- Error message or logs
- Steps you have already tried