Node.js Sandbox MCP Server

Servidor MCP Sandbox de Node.js

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.

👉 Mira la web oficial

Características

• Iniciar y administrar contenedores sandbox aislados de Node.js
• Ejecutar comandos de shell arbitrarios dentro de contenedores
• Instalar dependencias npm especificadas por trabajo
• Ejecute fragmentos de JavaScript del módulo ES y capture la salida estándar
• Desmontar los contenedores de forma limpia
• Modo separado: mantiene activo el contenedor después de la ejecución del script (por ejemplo, para servidores de larga duración)

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

Explora casos de uso interesantes

Si quieres ideas sobre formas interesantes y potentes de usar esta biblioteca, consulta la sección de casos de uso en el sitio web. Contiene una lista seleccionada de indicaciones, ejemplos y experimentos creativos que puedes probar con el servidor MCP Sandbox de Node.js.

⚠️ Requisitos previos

Para utilizar este servidor MCP, Docker debe estar instalado y ejecutándose en su máquina.

Consejo: extraiga con antelación todas las imágenes de Docker que necesitará para evitar demoras durante la primera ejecución.

Ejemplos de imágenes recomendadas:

• nodo
• mcr.microsoft.com/playwright.52.0-noble
• alfonsograziano/node-chartjs-canvas:último

Empezando

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

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

• Validar que la herramienta pueda 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ía poder ver Hola mundo.
• Validar que se puedan 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 el directorio montado (por ejemplo, el Escritorio) llamado "qrcode.png"

Uso con Claude Desktop

Agregue esto a su claude_desktop_config.json : Puede seguir la Guía oficial para instalar este servidor MCP

o con NPX:

Nota: asegúrese de que su directorio de trabajo apunte al servidor creado y que Docker esté instalado/en ejecución.

Estibador

Ejecute el servidor en un contenedor (monte el socket Docker si es necesario) y pase el directorio de salida del host deseado como una variable de entorno:

Este enlace monta su carpeta de host en el contenedor en la misma ruta absoluta y hace que FILES_DIR esté disponible dentro del servidor MCP.

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 : agregue a su archivo VS Code settings.json o .vscode/mcp.json :

API

Herramientas

run_js_efímero

Ejecute un script JS único en un contenedor desechable nuevo.

Entradas:

• image (cadena, opcional): imagen de Docker a utilizar (predeterminada: node:lts-slim ).
• code (cadena, obligatorio): código fuente JavaScript a ejecutar.
• dependencies (matriz de { name, version } , opcional): paquetes y versiones NPM para instalar (predeterminado: [] ).

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. Desmonta (quita) el contenedor.
6. Devuelve la salida estándar capturada.
7. Si su código guarda algún archivo 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 guardar archivos actualmente solo está disponible en la herramienta efímera.

Consejo: para recuperar los archivos, simplemente guárdelos durante la ejecución del script.

Ejemplo de llamada:

Ejemplo para guardar un archivo:

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

inicialización de sandbox

Inicie un nuevo contenedor de arena.

• Aporte :
  • image ( cadena , opcional, valor predeterminado: node:lts-slim ): imagen de Docker para el entorno sandbox
  • port ( número , opcional): si se configura, asigna este puerto de contenedor al host
• Salida : cadena de identificación del contenedor

sandbox_exec

Ejecute comandos de shell dentro del entorno sandbox en ejecución.

• Aporte :
  • container_id ( cadena ): ID de sandbox_initialize
  • commands ( string[] ): Matriz de comandos de shell para ejecutar
• Salida : Salida estándar combinada de cada comando

ejecutar_js

Instalar las dependencias npm y ejecutar el código JavaScript.

• Aporte :
  • container_id ( cadena ): ID de sandbox_initialize
  • code ( cadena ): código fuente JS para ejecutar (módulos ES compatibles)
  • dependencies ( matriz de { name, version } , opcional, predeterminado: [] ): nombres de paquetes npm → versiones semver
  • listenOnPort ( número , opcional): si se configura, deja el proceso en ejecución y expone este puerto al host ( modo separado )
• Comportamiento:
  1. Crea un espacio de trabajo temporal dentro del contenedor
  2. Escribe index.js y un paquete mínimo package.json
  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 ejecutándose en segundo plano si listenOnPort está configurado
  5. Limpia el espacio de trabajo a menos que se ejecute en modo separado
• Salida : Salida estándar del script o aviso de ejecución en segundo plano

parada de la zona de pruebas

Terminar y eliminar el contenedor sandbox.

• Aporte :
  • container_id ( cadena ): ID de sandbox_initialize
• Salida : Mensaje de confirmación

Consejos de uso

• Las herramientas basadas en sesiones ( sandbox_initialize ➔ run_js ➔ sandbox_stop ) son ideales cuando desea:
  • Mantenga abierto el contenedor de arena de larga duración.
  • Ejecute múltiples comandos o scripts en el mismo entorno.
  • Instalar y reutilizar dependencias de forma incremental.
• La ejecución única con run_js_ephemeral es perfecta para:
  • Experimentos rápidos o scripts simples.
  • Casos en los que no es necesario mantener dependencias de estado o caché.
  • Funcionamiento limpio y atómico sin preocuparse por el desmontaje manual.
• El modo separado es útil cuando desea:
  • Ponga en marcha servidores o servicios de larga duración sobre la marcha
  • Exponer y probar puntos finales desde contenedores en ejecución

¡Elija el flujo de trabajo que mejor se adapte a su caso de uso!

Construir

Compilar y agrupar:

Licencia

Licencia MIT

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

El aviso de derechos de autor 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, INCLUYENDO, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO 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ÑOS U OTRAS RESPONSABILIDADES, YA SEA EN ACCIÓN CONTRACTUAL, EXTRACONTRACTUAL O DE OTRO TIPO, QUE SURJA DE, SE DERIVE DE O EN RELACIÓN CON EL SOFTWARE O EL USO U OTRAS RELACIONES CON EL MISMO.