rbx-studio-mcp

Roblox Studio MCP

Permite que un agente de IA controle Roblox Studio: lee tu lugar, edita scripts, construye geometría, ejecuta playtests, toma capturas de pantalla. 35 herramientas. MIT.

Instalación

1. El plugin

npx -y @el4cteo/rbx-studio-mcp --install-plugin

O coloca StudioMCP.rbxmx desde Releases en tu carpeta de plugins de Studio.

2. El servidor

claude mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp

codex mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp

{
  "mcpServers": {
    "roblox-studio": {
      "command": "npx",
      "args": ["-y", "@el4cteo/rbx-studio-mcp"]
    }
  }
}

{
  "mcp": {
    "roblox-studio": {
      "type": "local",
      "command": ["npx", "-y", "@el4cteo/rbx-studio-mcp"],
      "enabled": true
    }
  }
}

3. Abre Studio y acepta el mensaje de 127.0.0.1. Verifica que funciona con studio_status.

¿Algo falla? Ejecuta npx -y @el4cteo/rbx-studio-mcp doctor — indica qué está roto y cómo solucionarlo.

El puerto es 44755, solo loopback. Cámbialo con --port y hazlo coincidir en el plugin.

Herramientas

Las herramientas de escritura aceptan arrays — diez ediciones de script es una sola llamada, un Ctrl+Z, y todo o nada.

Inspeccionar el cliente en ejecución

Durante un playtest, los lectores pueden ejecutarse en la propia VM del jugador (usa el studioId del servidor de playtest; agrega player="Name" con varios jugadores):

tree target="client" path="Players.Alice.PlayerGui" handles=true
inspect target="client" paths=["<handle>"] properties=["Text","AbsoluteSize"]
find target="client" className="TextButton"
viewport op="ui" target="client"
viewport op="pick" x=0.5 y=0.5 target="client"
performance op="snapshot" target="client"
debug op="watch" path=... target="client" properties=["Text"] seconds=5
debug op="collisions" path="Workspace.Ball" minSpeed=5 seconds=5

• Handles (handles=true) son referencias de sesión que reemplazan rutas. Sobreviven a renombrados y movimientos, y fallan en lugar de apuntar al objeto equivocado una vez eliminados o expirados.
• pick devuelve el objeto bajo un punto de pantalla (normalizado sobre el viewport completo).
• watch registra cambios de propiedades, atributos y hijos durante 1-15 segundos. Envía entrada en paralelo para ver una reacción.
• collisions informa qué golpeó una parte, o cada parte en un modelo: punto de contacto, normal, velocidad de impacto y área, primero el más fuerte. Requiere un playtest en ejecución.
• Resultados recortados de execute_luau devuelven un resultId. Navega con source omitido; nada se vuelve a ejecutar. Los resultados se conservan durante 120 segundos.

Trabajar con archivos

sync refleja tus scripts en una carpeta, para que un agente pueda editar código con sus propias herramientas de archivo y usar Studio para probar.

sync op="pull"      # Studio -> ./studio
sync op="push"      # ./studio -> Studio
sync op="watch"     # both ways, live, until op="stop"

• Diseño estilo Rojo: Main.server.luau, .client.luau, .luau; un script con hijos es una carpeta con init. Se escribe un sourcemap.json para luau-lsp.
• Renombra o mueve un archivo y el script se mueve con él, conservando sus atributos y referencias.
• ¿Editado en ambos lados? Es un conflicto y ningún lado se toca. La versión de Studio espera en .rbx-sync/conflicts/; fusiona en el archivo y sincroniza de nuevo, o pasa prefer: "studio" / "disk".
• Eliminar un archivo elimina el script (un Ctrl+Z). Un script eliminado en Studio envía su archivo a .rbx-sync/trash.
• export escribe UI o cualquier árbol de instancias como archivo .build.json; edítalo y build lo reconstruye, conservando sus scripts. Las ediciones hechas en Studio fluyen de vuelta al archivo.
• watch solo funciona cuando algo cambia: aproximadamente 0.5s en cada dirección, incluso con 2,000 scripts. Los conflictos aparecen en la siguiente respuesta del agente.

Open Cloud

Algunas llamadas llegan más allá de Studio hasta Roblox mismo. Todas necesitan una clave API; todo lo demás funciona sin ella.

Crea una clave en Creator Dashboard → Credentials, agregando los permisos que quieras: assets, universe-datastores, ordered-data-stores, luau-execution-sessions, universe-places, universe-place-instances, universe, messaging-service, user-restrictions, inventory, users, asset-permissions, developer-products, game-passes, universe-analytics. Programar eventos necesita los permisos universe.event:read y :write.

Luego, en el panel de Studio:

cloud key <paste>
cloud user <your user id>
cloud place <place id>

cloud place deduce el universo por ti. La clave escrita está enmascarada en el registro y en el historial, y se almacena en ~/.rbx-studio-mcp/credentials.json (modo 0600) — nunca en el archivo del lugar, nunca en la conversación. cloud muestra lo que está configurado, cloud test lo vuelve a verificar, cloud forget lo elimina. ROBLOX_API_KEY y similares en el entorno también funcionan y tienen prioridad.

Dos cosas a tener en cuenta: un playtest conecta una segunda sesión, así que pasa studioId y usa la de edición para cambios que deben durar; la emulación de device permanece activa hasta device op="stop".

El panel de consola

Cada llamada se registra con el tiempo que tomó. Al pie del panel hay una línea de comandos. Escribe un comando — o ejecuta chat on y escribe una frase para que un agente de codificación la responda.

Haz clic en la barra y cada comando se lista con lo que hace. Sigue escribiendo para filtrar, desplázate para el resto, haz clic en uno para completarlo.

Con chat on, los prompts inician un agente real — cualquiera que tengas en PATH: Claude Code, Codex, opencode, Gemini, Cursor, Amp, Qwen Code, Factory Droid, goose, Copilot CLI, Aider, Crush, DeepSeek Harness. Se ejecuta sin interfaz, controla el mismo Studio, y su trabajo aparece en el registro. Es una sesión separada de tu terminal, facturada por separado, y solo se le permiten las herramientas rbx-studio. El botón stop junto al prompt lo cancela.

Ocho temas detrás de la pestaña en el borde derecho. Tu elección se recuerda.

Por qué este

• Push, no poll — 13.6 ms por llamada frente a 25.8 ms.
• Ediciones de script seguras — las escrituras pasan por el editor de scripts, por lo que el trabajo no guardado sobrevive.
• Las ediciones obsoletas se rechazan — devuelve el rev de script_read y una escritura solo se aplica si nadie más tocó el archivo.
• Los nombres de propiedades se verifican contra el motor en ejecución, por lo que Anchorred vuelve como sugerencia, no como error en tiempo de ejecución.

DeepSeek Harness (dsh)

Este servidor se registra como plugin de dsh. Agrega esta fila a $DSH_HOME/cordis.patch.yml, o a $DSH_HOME/profiles/<name>/cordis.patch.yml para un solo perfil:

- insert:
    - id: mcp-rbx-studio
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: rbx-studio
        transport: stdio
        command: npx
        args: ['-y', '@el4cteo/rbx-studio-mcp']
        cwd: !!js process.cwd()

Luego dsh --profile headless "what is in workspace". Necesita DEEPSEEK_API_KEY. La misma fila, comentada, está en config/dsh.cordis.yml para usar con dsh --patch.

Seguridad

Solo loopback. Las solicitudes necesitan un encabezado que un navegador no puede establecer entre orígenes y un Host de loopback, por lo que una página web no puede alcanzarlo, ni siquiera mediante DNS rebinding. La configuración "Allow HTTP Requests" de tu experiencia no se toca.

Desarrollo

npm install
npm run build          # TypeScript -> dist/
npm run install:plugin # build the plugin and copy it into Studio
npm test

Necesita luau, luau-compile y luau-analyze de los lanzamientos de Luau en PATH o en tools/.

Con Studio abierto y el plugin cargado, node scripts/test-live.mjs verifica el transporte y node scripts/test-live-tools.mjs [--playtest] ejecuta cada herramienta, node scripts/test-live-sync.mjs verifica sync, y node scripts/test-live-sync-scale.mjs lo cronometra en 2,000 scripts. Todo se limpia solo.

Licencia

MIT.