Node.js Sandbox MCP Server

Ejecuta JavaScript arbitrario en un contenedor Docker aislado con instalación de dependencias npm sobre la marcha.

GitHub
157
Prueba este MCPPatrocinado

Documentación

🐢🚀 Node.js Sandbox MCP Server

Servidor Node.js que implementa el Protocolo de Contexto de Modelo (MCP) para ejecutar JavaScript arbitrario en contenedores Docker efímeros con instalación de dependencias npm sobre la marcha.

Website Preview

👉 Mira el sitio web oficial

📦 Disponible en Docker Hub

Características

  • Iniciar y gestionar contenedores sandbox de Node.js aislados
  • Ejecutar comandos de shell arbitrarios dentro de los contenedores
  • Instalar dependencias npm especificadas por trabajo
  • Ejecutar fragmentos de JavaScript con módulos ES y capturar la salida estándar
  • Eliminar contenedores de forma limpia
  • Modo Desacoplado: Mantener el contenedor vivo después de la ejecución del script (por ejemplo, para servidores de larga duración)

Nota: Los contenedores se ejecutan con límites controlados de CPU/memoria.

Explora Casos de Uso Interesantes

Si quieres ideas para formas interesantes y potentes de usar esta librería, consulta la sección de casos de uso en el sitio web. Contiene una lista curada de prompts, ejemplos y experimentos creativos que puedes probar con el Node.js Sandbox MCP Server.

⚠️ Requisitos Previos

Para usar este servidor MCP, Docker debe estar instalado y en ejecución en tu máquina.

Consejo: Descarga previamente las imágenes de Docker que necesites para evitar retrasos durante la primera ejecución.

Ejemplos de imágenes recomendadas:

  • node:lts-slim
  • mcr.microsoft.com/playwright:v1.55.0-noble
  • alfonsograziano/node-chartjs-canvas:latest

Primeros Pasos

Para comenzar con este servidor MCP, primero debes conectarlo a un cliente (por ejemplo, Claude Desktop).

Una vez que esté en ejecución, puedes probar que funciona correctamente con un par de prompts de prueba:

  • Validar que la herramienta puede ejecutarse:

    Create and run a JS script with a console.log("Hello World")

    Esto debería ejecutar un console.log y en la respuesta de la herramienta deberías poder ver Hello World.

  • Validar que puedes instalar dependencias y guardar archivos

    Create and run a JS script that generates a QR code for the URL `https://nodejs.org/en`, and save it as `qrcode.png` **Tip:** Use the `qrcode` package.

    Esto debería crear un archivo en tu directorio montado (por ejemplo, el Escritorio) llamado "qrcode.png"

Uso con Claude Desktop

Añade esto a tu claude_desktop_config.json: Puedes seguir la Guía Oficial para instalar este servidor MCP

{
  "mcpServers": {
    "js-sandbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "-v",
        "$HOME/Desktop/sandbox-output:/root",
        "-e",
        "FILES_DIR=$HOME/Desktop/sandbox-output",
        "-e",
        "SANDBOX_MEMORY_LIMIT=512m", // optional
        "-e",
        "SANDBOX_CPU_LIMIT=0.75", // optional
        "mcp/node-code-sandbox"
      ]
    }
  }
}

o con NPX:

{
  "mcpServers": {
    "node-code-sandbox-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-code-sandbox-mcp"],
      "env": {
        "FILES_DIR": "/Users/alfonsograziano/Desktop/node-sandbox",
        "SANDBOX_MEMORY_LIMIT": "512m", // optional
        "SANDBOX_CPU_LIMIT": "0.75" // optional
      }
    }
  }
}

Nota: Asegúrate de que tu directorio de trabajo apunte al servidor compilado y de que Docker esté instalado/en ejecución.

Docker

Ejecuta el servidor en un contenedor (monta el socket de Docker si es necesario) y pasa tu directorio de salida deseado del host como variable de entorno:

# Build locally if necessary
# docker build -t mcp/node-code-sandbox .

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$HOME/Desktop/sandbox-output":"/root" \
  -e FILES_DIR="$HOME/Desktop/sandbox-output" \
  -e SANDBOX_MEMORY_LIMIT="512m" \
  -e SANDBOX_CPU_LIMIT="0.5" \
  mcp/node-code-sandbox stdio

Esto monta tu carpeta del host en el contenedor en la misma ruta absoluta y hace que FILES_DIR esté disponible dentro del servidor MCP.

Uso efímero – sin almacenamiento persistente

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  alfonsograziano/node-code-sandbox-mcp stdio

Uso con VS Code

Botones de instalación rápida (VS Code e Insiders):

Instalar js-sandbox-mcp (NPX) Instalar js-sandbox-mcp (Docker)

Configuración manual: Añade a tu settings.json o .vscode/mcp.json de VS Code:

"mcp": {
    "servers": {
        "js-sandbox": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-v", "/var/run/docker.sock:/var/run/docker.sock",
                "-v", "$HOME/Desktop/sandbox-output:/root", // optional
                "-e", "FILES_DIR=$HOME/Desktop/sandbox-output",  // optional
                "-e", "SANDBOX_MEMORY_LIMIT=512m",
                "-e", "SANDBOX_CPU_LIMIT=1",
                "mcp/node-code-sandbox"
              ]
        }
    }
}

API

Herramientas

run_js_ephemeral

Ejecuta un script JS único en un contenedor desechable completamente nuevo.

Entradas:

  • image (string, opcional): Imagen de Docker a utilizar (por defecto: node:lts-slim).
  • code (string, obligatorio): Código fuente de JavaScript a ejecutar.
  • dependencies (array de { name, version }, opcional): Paquetes y versiones npm a instalar (por defecto: []).

Comportamiento:

  1. Crea un contenedor nuevo.
  2. Escribe tu index.js y un package.json mínimo.
  3. Instala las dependencias especificadas.
  4. Ejecuta el script.
  5. Elimina (remueve) el contenedor.
  6. Devuelve la salida estándar capturada.
  7. Si tu código guarda archivos en el directorio actual, estos archivos se devolverán automáticamente.
    • Las imágenes (por ejemplo, PNG, JPEG) se devuelven como contenido image.
    • Otros archivos (por ejemplo, .txt, .json) se devuelven como contenido resource.
    • Nota: la función de guardado de archivos está disponible actualmente solo en la herramienta efímera.

Consejo: Para recuperar archivos, simplemente guárdalos durante la ejecución de tu script.

Ejemplo de llamada:

{
  "name": "run_js_ephemeral",
  "arguments": {
    "image": "node:lts-slim",
    "code": "console.log('One-shot run!');",
    "dependencies": [{ "name": "lodash", "version": "^4.17.21" }],
  },
}

Ejemplo para guardar un archivo:

import fs from 'fs/promises';

await fs.writeFile('hello.txt', 'Hello world!');
console.log('Saved hello.txt');

Esto devolverá la salida de consola y el archivo hello.txt.

sandbox_initialize

Inicia un contenedor sandbox nuevo.

  • Entrada:
    • image (string, opcional, por defecto: node:lts-slim): Imagen de Docker para el sandbox
    • port (number, opcional): Si se establece, mapea este puerto del contenedor al host
  • Salida: Cadena con el ID del contenedor

sandbox_exec

Ejecuta comandos de shell dentro del sandbox en ejecución.

  • Entrada:
    • container_id (string): ID de sandbox_initialize
    • commands (string[]): Array de comandos de shell a ejecutar
  • Salida: Salida estándar combinada de cada comando

run_js

Instala dependencias npm y ejecuta código JavaScript.

  • Entrada:

    • container_id (string): ID de sandbox_initialize
    • code (string): Código fuente JS a ejecutar (compatible con módulos ES)
    • dependencies (array de { name, version }, opcional, por defecto: []): Nombres de paquetes npm → versiones semver
    • listenOnPort (number, opcional): Si se establece, deja el proceso en ejecución y expone este puerto al host (Modo Desacoplado)

  • Comportamiento:

    1. Crea un espacio de trabajo temporal dentro del contenedor
    2. Escribe index.js y un package.json mínimo
    3. Ejecuta npm install --omit=dev --ignore-scripts --no-audit --loglevel=error
    4. Ejecuta node index.js y captura la salida estándar, o deja el proceso en ejecución en segundo plano si listenOnPort está establecido
    5. Limpia el espacio de trabajo a menos que se ejecute en modo desacoplado

  • Salida: Salida estándar del script o aviso de ejecución en segundo plano

sandbox_stop

Termina y elimina el contenedor sandbox.

  • Entrada:
    • container_id (string): ID de sandbox_initialize
  • Salida: Mensaje de confirmación

search_npm_packages

Busca paquetes npm por un término de búsqueda y obtén su nombre, descripción y un fragmento del README.

  • Entrada:

    • searchTerm (string, obligatorio): El término a buscar en los paquetes npm. Debe contener todo el contexto relevante. Usa signos más (+) para combinar términos relacionados (por ejemplo, "react+components" para librerías de componentes React).
    • qualifiers (object, opcional): Calificadores opcionales para filtrar los resultados de búsqueda:
      • author (string, opcional): Filtrar por nombre del autor del paquete
      • maintainer (string, opcional): Filtrar por nombre del mantenedor del paquete
      • scope (string, opcional): Filtrar por scope de npm (por ejemplo, "@vue" para paquetes de Vue.js)
      • keywords (string, opcional): Filtrar por palabras clave del paquete
      • not (string, opcional): Excluir paquetes que coincidan con este criterio (por ejemplo, "insecure")
      • is (string, opcional): Incluir solo paquetes que coincidan con este criterio (por ejemplo, "unstable")
      • boostExact (string, opcional): Potenciar coincidencias exactas para este término en los resultados de búsqueda

  • Comportamiento:

    1. Busca en el registro npm usando el término de búsqueda y los calificadores proporcionados
    2. Devuelve hasta 5 paquetes ordenados por popularidad
    3. Para cada paquete, proporciona nombre, descripción y fragmento del README (primeros 500 caracteres)

  • Salida: Array JSON con los detalles de los paquetes, incluyendo nombre, descripción y fragmento del README

Consejos de Uso

  • Herramientas basadas en sesión (sandbox_initialize ➔ run_js ➔ sandbox_stop) son ideales cuando quieres:
    • Mantener un contenedor sandbox de larga duración abierto.
    • Ejecutar múltiples comandos o scripts en el mismo entorno.
    • Instalar y reutilizar dependencias de forma incremental.
  • Ejecución única con run_js_ephemeral es perfecta para:
    • Experimentos rápidos o scripts simples.
    • Casos en los que no necesitas mantener estado ni almacenar en caché dependencias.
    • Ejecuciones limpias y atómicas sin preocuparte por la eliminación manual.
  • Modo desacoplado es útil cuando quieres:
    • Levantar servidores o servicios de larga duración sobre la marcha
    • Exponer y probar endpoints desde contenedores en ejecución

¡Elige el flujo de trabajo que mejor se adapte a tu caso de uso!

Compilación

Compilar y empaquetar:

npm install
npm run build

Licencia

Licencia MIT

Por la presente se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y de los archivos de documentación asociados (el "Software"), para tratar el Software sin restricción, incluidos, sin limitación, los derechos de usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir a las personas a quienes se les proporcione el Software hacer lo mismo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUIDAS, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE, O EN CONEXIÓN CON, EL SOFTWARE O EL USO U OTRO TIPO DE ACCIONES EN EL SOFTWARE.