Guía para reducir paso a paso los problemas de conexión, permisos, Sync y validación.
Cuando el plugin no se conecta
Síntoma: Se muestra “Connection failed” o el plugin aparece como no conectado en Roblox Studio.
- Verifica que el servidor MCP esté en ejecución:
npx -y @weppy/roblox-mcp - Roblox Studio: pestaña Plugins → WEPPY → clic en Connect
- Verifica que no haya un firewall, antivirus o VPN que bloquee
localhost:3002 - Reinicia tanto Roblox Studio como el servidor MCP
Cuando el cliente de IA no reconoce el servidor MCP
- Verifica que se use el comando correcto en la configuración del cliente de IA:
npx -y @weppy/roblox-mcp - Verifica que Node.js 18 o superior esté instalado:
node --version - En Windows, si se produce un error de permisos, intenta ejecutar el terminal como administrador
- Consulta la guía de instalación de la app de IA que usas
Aviso “Pro feature required”
Cuando solicitas una acción exclusiva de Pro desde Basic, si es posible se busca un método alternativo. Sin embargo, el flujo alternativo consume tokens adicionales y no siempre garantiza el mismo resultado.
Además, algunas herramientas exclusivas de Pro que no pueden ejecutarse de forma alternativa no se pueden usar desde Basic. Si este aviso aparece repetidamente, considera cambiar a Pro.
Cuando Sync no funciona
- Verifica el estado de Sync: solicita a la IA
manage_sync status - Verifica que el plugin esté conectado antes de iniciar Sync
- Si el sync inverso (archivo → Studio) no funciona, verifica si el tier Pro está activado
- Verifica que la carpeta de sync local exista y tenga permisos de escritura
Para ver la configuración detallada de Sync, consulta Sync bidireccional.
Clientes de IA compatibles
| Cliente | Basic | Pro |
|---|---|---|
| Claude Code | ✅ | ✅ |
| Claude Desktop | ✅ | ✅ |
| Cursor | ✅ | ✅ |
| Codex CLI | ✅ | ✅ |
| Codex Desktop | ✅ | ✅ |
| Gemini CLI | ✅ | ✅ |
| Apps con soporte MCP | ✅ | ✅ |
Comando del servidor: npx -y @weppy/roblox-mcp
Requisitos del sistema
| Ítem | Mínimo |
|---|---|
| Node.js | 18.0.0 o superior |
| Roblox Studio | Última versión (mantener actualizaciones automáticas) |
| Sistema operativo | Windows 10+ o macOS 12+ |
| Red | Debe poder acceder a localhost:3002 |
Comparación de funciones Basic vs Pro
Basic (gratuito) también permite usar la mayor parte del flujo principal de codificación con IA. Incluye todas las herramientas principales para gestionar instancias, propiedades, scripts, selección, cámara y logs, y también permite usar Sync unidireccional Studio → Local y el historial de ejecución de herramientas. Pro añade Sync bidireccional, operaciones masivas, y un conjunto de herramientas avanzadas como terreno, iluminación, física, audio y animaciones.
| Función | Basic | Pro |
|---|---|---|
| Buscar, crear, eliminar, clonar y mover instancias | ✅ | ✅ |
| Explorar árbol y jerarquía de instancias | ✅ | ✅ |
| Leer y escribir propiedades y etiquetas | ✅ | ✅ |
| Leer, escribir y modificar scripts | ✅ | ✅ |
| Gestión de selección | ✅ | ✅ |
| Mover y enfocar la cámara | ✅ | ✅ |
| Consultar logs | ✅ | ✅ |
| Información del sistema y verificación de conexión | ✅ | ✅ |
| Historial y estadísticas de ejecución de herramientas | ✅ | ✅ |
| Sync unidireccional Studio → Local | ✅ | ✅ |
| Sync bidireccional (Local → Studio) | — | ✅ |
| Direction / Apply Mode por tipo | — | ✅ |
| Historial de cambios de Sync | — | ✅ |
| Sincronización multi-Place (hasta 3) | — | ✅ |
| Operaciones masivas (creación/modificación en lote) | — | ✅ |
| Control de iluminación y atmósfera | — | ✅ |
| Creación y edición de terreno | — | ✅ |
| Control de tweens y animaciones | — | ✅ |
| Control de audio | — | ✅ |
| Partículas y efectos | — | ✅ |
| Grupos de física y colisiones | — | ✅ |
| Consultas espaciales y raycasts | — | ✅ |
| Buscar, insertar y exportar assets | — | ✅ |
| Captura de pantalla | — | ✅ |
| Ejecución y inyección automática de pruebas en Playtest | — | ✅ |
| Ejecución en lote y código Luau arbitrario | — | ✅ |
Si solicitas funciones exclusivas de Pro desde Basic, se intenta encontrar una solución alternativa, pero el consumo de tokens aumenta y algunas funciones no pueden ejecutarse de forma alternativa. Consulta el elemento Aviso “Pro feature required” de arriba para más detalles.
Mensajes de error frecuentes
| Error | Causa | Solución |
|---|---|---|
ECONNREFUSED localhost:3002 | Servidor MCP no ejecutándose | Ejecutar npx -y @weppy/roblox-mcp |
Timeout waiting for plugin | Plugin de Studio no conectado | Hacer clic en Connect en el panel del plugin |
Forbidden path | Intento de acceso a CoreGui/CorePackages | Usar solo rutas de instancias válidas |
Place ID mismatch | Conectado al Place incorrecto | Reconectar desde la sesión correcta de Studio |
Si necesitas ayuda
Si el problema sigue sin resolverse, escribe en GitHub Discussions con la siguiente información:
- Sistema operativo y versión de Node.js
- Cliente de IA y su versión
- Mensaje de error o logs
- Pasos que ya has intentado