# Mcp Roblox Studio

> Servidor MCP que conecta Claude (y otros clientes MCP) con Roblox Studio. Construye scripts, mapas y modelos directo desde la IA. Por PyroxSolutions.

- **Type:** MCP server
- **Install:** `agentstack add mcp-pyroxsolution-mcp-roblox-studio`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PyroxSolution](https://agentstack.voostack.com/s/pyroxsolution)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [PyroxSolution](https://github.com/PyroxSolution)
- **Source:** https://github.com/PyroxSolution/mcp-roblox-studio
- **Website:** https://github.com/PyroxSolution/mcp-roblox-studio

## Install

```sh
agentstack add mcp-pyroxsolution-mcp-roblox-studio
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Roblox Studio

Servidor MCP que conecta cualquier cliente compatible (Claude Desktop, Claude Code,
Cursor, Continue...) con Roblox Studio. La idea es simple: hablas con la IA, ella
construye dentro de tu place. Scripts, mapas, modelos, todo en vivo.

Lo construí en PyroxSolutions porque me cansé de copiar y pegar Lua entre la ventana
del LLM y Studio. Funciona desde diciembre de 2025 en producción interna; lo libero
ahora para que cualquiera pueda usarlo.

> Desarrollado por **[PyroxSolutions](https://github.com/PyroxSolution)**, herramientas
> para devs de Roblox que prefieren construir más y configurar menos.

---

## ¿Qué puede hacer?

Lista corta de cosas que ya he hecho con esto:

- "Construye un obby de 10 plataformas con lava abajo." → 30 segundos.
- "Lee todos los scripts de ServerScriptService y dime dónde está el bug del datastore." → 2 minutos.
- "Genera un mapa para un juego de subastas tipo Storage Wars con lobby, casa de subastas, 12 garajes y 12 plots de tienda." → ~1 minuto, 444 parts.
- "Inserta el asset 1234567 y alinéalo al baseplate." → instantáneo.
- "Crea un LocalScript en StarterPlayerScripts que duplique la velocidad cuando aprieto Shift." → 5 segundos.

No es magia. Es un puente HTTP entre tu IA y la API de plugins de Studio. Pero ahorra
tiempo.

## Cómo se ve por dentro

```
   ┌──────────────┐  stdio   ┌─────────────────┐  HTTP local  ┌────────────────┐
   │ Cliente MCP  │────────▶ │  Servidor MCP   │ ───────────▶ │ Plugin Studio  │
   │  (la IA)     │ JSON-RPC │  (Node.js)      │ JSON 127.0.0.1│  (Lua)         │
   └──────────────┘          └─────────────────┘              └────────────────┘
```

Tres procesos, ninguno expuesto a internet. Toda la comunicación pasa por `127.0.0.1`.

---

## Instalar (5 minutos)

### Requisitos

- Node.js 18 o más nuevo (`node --version` para confirmar).
- Roblox Studio.
- Un cliente MCP. Yo recomiendo Claude Desktop si nunca has usado uno; es el más
  amigable. Claude Code y Cursor también funcionan.

### Paso 1: clonar y compilar

```bash
git clone https://github.com/PyroxSolution/mcp-roblox-studio.git
cd mcp-roblox-studio
npm install
npm run build:all
```

Eso te deja:
- `dist/index.js`, el servidor MCP listo para correr.
- `plugin/build/MCPRobloxStudio.rbxmx`, el plugin de Studio listo para arrastrar.

### Paso 2: instalar el plugin

Copia el `.rbxmx` a tu carpeta de plugins de Studio:

**Windows:**
```powershell
copy plugin\build\MCPRobloxStudio.rbxmx "$env:LOCALAPPDATA\Roblox\Plugins\"
```

**macOS:**
```bash
mkdir -p ~/Documents/Roblox/Plugins
cp plugin/build/MCPRobloxStudio.rbxmx ~/Documents/Roblox/Plugins/
```

Reinicia Studio. Vas a ver un nuevo botón **MCP** en la pestaña Plugins.

> Si prefieres no usar el `.rbxmx`: abre `plugin/src/MCPRobloxStudio.server.lua`, copia
> todo, pégalo en un Script vacío en cualquier place, click derecho al script →
> **Save as Local Plugin**. Mismo resultado.

### Paso 3: registrar el servidor en tu cliente

**Claude Desktop** (lo más fácil):

1. Abre Claude Desktop → Settings → Developer → **Editar configuración**.
2. Pega esto reemplazando lo que haya:

```json
{
  "mcpServers": {
    "roblox-studio": {
      "command": "node",
      "args": ["C:\\ruta\\absoluta\\al\\repo\\dist\\index.js"]
    }
  }
}
```

3. Guarda, cierra completamente Claude Desktop (incluido el ícono de la bandeja del
   sistema), reábrelo. En Settings → Developer debe aparecer `roblox-studio` como
   **running**.

**Claude Code:**

```bash
claude mcp add -s user roblox-studio -- node /ruta/absoluta/al/repo/dist/index.js
```

El flag `-s user` es importante: registra el servidor como global, no atado a una
carpeta específica. Si no lo pones te va a aparecer "Failed to connect" cuando uses
`claude` desde otro directorio.

**Cursor / Continue:** ver [docs/INSTALL.md](docs/INSTALL.md), formato similar.

### Paso 4: conectar el plugin

1. La primera vez que tu cliente MCP arranque el servidor, este genera un token y lo
   guarda en `~/.mcp-roblox-studio/config.json`. Ábrelo y copia el valor del campo
   `token`.
2. En Studio abre el panel **MCP** (pestaña Plugins → botón MCP).
3. Pega el token en el campo Token, deja host/port en los defaults.
4. Click en **Connect**. La pastilla pasa de roja a verde.

A partir de aquí, mientras tu cliente MCP esté corriendo el plugin se puede conectar.
El token queda guardado en los settings del plugin, así que solo lo pegas una vez.

### Paso 5: probar

En el chat de tu cliente MCP, escribe:

```
Llama studio_status del MCP roblox-studio
```

Si todo está bien te responde con `connected: true` y los datos de tu place. Después
prueba algo más interesante:

```
Crea un Part rojo neón en posición 0, 30, 0 con tamaño 8x8x8
```

Vas a ver el cubo aparecer en vivo en Studio.

---

## Las herramientas que la IA puede usar

15 herramientas, divididas por propósito. Documentación completa con ejemplos en
[docs/TOOLS.md](docs/TOOLS.md).

**Estado y depuración:**
- `studio_status`, saber si el plugin está conectado.
- `get_console`, leer las últimas N líneas de la consola de Studio.

**El comodín:**
- `run_lua`, ejecutar Lua arbitrario con permisos de plugin. Es la herramienta más
  poderosa; la IA la usa cuando necesita hacer algo que no encaja en las otras.

**Inspección:**
- `get_tree`, árbol JSON de la jerarquía del data model.
- `get_instance`, todas las propiedades de una instancia.
- `search_instances`, buscar por nombre y/o ClassName.
- `get_selection`, qué tiene seleccionado el usuario.

**Mutación:**
- `create_instance`, `Instance.new(...)` con tabla de propiedades y parent.
- `set_properties`, asignar muchas propiedades de golpe.
- `delete_instance`, destruir.
- `select`, cambiar la selección del usuario en Studio.

**Scripts:**
- `create_script`, crear Script/LocalScript/ModuleScript con código.
- `get_script_source` / `set_script_source`, leer y reescribir.

**Construcción rápida:**
- `create_part`, atajo para spawnear un Part con shape, posición, color, material.
- `insert_asset`, `InsertService:LoadAsset(id)` y reparentar.

Todas las acciones que mutan están envueltas en `ChangeHistoryService`. Eso significa
que **Ctrl+Z deshace lo que la IA hizo**, igual que si lo hubieras hecho tú.

---

## Seguridad

Pongo esto temprano porque es importante:

1. **El bridge HTTP escucha solo en `127.0.0.1`.** Nada en tu red local lo puede
   alcanzar. No abras el puerto al exterior bajo ninguna circunstancia.
2. **Token aleatorio de 48 chars hex** por instalación. El plugin lo presenta en cada
   request. Defensa razonable contra otros procesos locales que intenten fuzzing.
3. **`run_lua` ejecuta cualquier Lua con permisos de plugin.** Sí, cualquier cosa.
   Eso significa que solo deberías conectar clientes MCP en los que confíes, porque
   le estás dando a la IA acceso completo a tu place.
4. **El config se guarda con permisos 600 en POSIX** (en Windows no aplica, los ACL
   son distintos).

Si te preocupa el riesgo de `run_lua`, puedes desactivar esa herramienta editando
[`src/tools.ts`](src/tools.ts) y rebuildeando. El resto de las herramientas son
mucho más limitadas en lo que pueden hacer.

---

## Documentación

- [docs/INSTALL.md](docs/INSTALL.md), instalación detallada para cada cliente MCP, variables de entorno, troubleshooting.
- [docs/TOOLS.md](docs/TOOLS.md), referencia completa de las 15 herramientas, codificación de tipos Roblox (Vector3, CFrame, Color3...), recetas listas para copiar.
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), cómo funciona el bridge por dentro, el ciclo de vida de una llamada, cómo extender con nuevas herramientas.
- [plugin/README.md](plugin/README.md), instalación y build del plugin desde fuente.

---

## Problemas comunes

| Síntoma | Solución |
|---|---|
| Plugin dice "Connection failed" | El servidor MCP no está corriendo. Asegúrate de que tu cliente esté abierto. En Claude Desktop, Settings → Developer debe mostrar `roblox-studio` running. |
| Plugin dice "HTTP 401" | Token incorrecto. Vuelve a copiarlo del archivo `~/.mcp-roblox-studio/config.json`. |
| Claude Code: "Failed to connect" | Probablemente registraste el MCP con scope local. Quita y vuelve a agregar con `-s user`. |
| `EADDRINUSE: 44755` | Hay otro proceso del servidor corriendo. Mata el `node.exe` colgado o cambia el puerto con `MCP_ROBLOX_PORT=otro_puerto`. |
| `Http requests are not enabled` | Raro pero pasa: en algunas versiones de Studio hay que activar Game Settings → Security → Allow HTTP Requests. Los plugins normalmente están exentos pero por si acaso. |
| Tools no aparecen en el cliente | Reinicia el cliente. Algunos no recargan los MCP en caliente. |

Si encuentras algo que no está aquí, abre un [issue](https://github.com/PyroxSolution/mcp-roblox-studio/issues).

---

## ¿Qué falta?

Lista honesta de lo que NO hace todavía:

- **No busca assets en el Toolbox por keyword.** La API de Roblox no expone búsqueda
  libre desde plugins. Tienes que darle IDs específicos.
- **No puede playtest interactivo.** Puede leer la consola y modificar el place,
  pero no puede caminar al personaje ni hacer clicks dentro del juego.
- **No soporta múltiples instancias de Studio simultáneas.** El bridge solo acepta
  un plugin a la vez.
- **No genera meshes ni texturas.** Solo Parts básicos. Para arte real necesitas
  el Toolbox o un artista.
- **DataStores en Studio requieren API access activado** (Game Settings → Security).
  Sin eso el plugin tiene un fallback en memoria pero no persiste.

---

## Contribuir

Si encuentras un bug o quieres agregar una herramienta, ver
[CONTRIBUTING.md](CONTRIBUTING.md). Issues y PRs bienvenidos.

## Licencia

MIT. Ver [LICENSE](LICENSE). Hecho por [PyroxSolutions](https://github.com/PyroxSolution).

---

Si esto te ahorra tiempo, una estrella ⭐ en GitHub no cuesta nada y me motiva a
mantenerlo. Gracias.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PyroxSolution](https://github.com/PyroxSolution)
- **Source:** [PyroxSolution/mcp-roblox-studio](https://github.com/PyroxSolution/mcp-roblox-studio)
- **License:** MIT
- **Homepage:** https://github.com/PyroxSolution/mcp-roblox-studio

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pyroxsolution-mcp-roblox-studio
- Seller: https://agentstack.voostack.com/s/pyroxsolution
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.