Node.js Sandbox MCP Server

Execute JavaScript arbitrário em um contêiner Docker isolado com instalação de dependências npm em tempo real.

GitHub
157
Experimente este MCPPatrocinado

Documentação

🐢🚀 Node.js Sandbox MCP Server

Servidor Node.js que implementa o Model Context Protocol (MCP) para executar JavaScript arbitrário em contêineres Docker efêmeros com instalação de dependências npm em tempo real.

Website Preview

👉 Veja o site oficial

📦 Disponível no Docker Hub

Recursos

  • Iniciar e gerenciar contêineres sandbox Node.js isolados
  • Executar comandos shell arbitrários dentro dos contêineres
  • Instalar dependências npm especificadas por job
  • Executar trechos de JavaScript em módulo ES e capturar o stdout
  • Encerrar contêineres de forma limpa
  • Modo Destacado: Manter o contêiner ativo após a execução do script (por exemplo, para servidores de longa duração)

Nota: Os contêineres são executados com limites controlados de CPU/memória.

Explore Casos de Uso Interessantes

Se você quer ideias de maneiras interessantes e poderosas de usar esta biblioteca, confira a seção de casos de uso no site. Ela contém uma lista selecionada de prompts, exemplos e experimentos criativos que você pode testar com o Node.js Sandbox MCP Server.

⚠️ Pré-requisitos

Para usar este servidor MCP, o Docker deve estar instalado e em execução na sua máquina.

Dica: Pré-baixe as imagens Docker que você precisará para evitar atrasos durante a primeira execução.

Exemplos de imagens recomendadas:

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

Primeiros passos

Para começar com este servidor MCP, primeiro você precisa conectá-lo a um cliente (por exemplo, Claude Desktop).

Depois que estiver em execução, você pode testar se está funcionando totalmente com alguns prompts de teste:

  • Validar que a ferramenta pode ser executada:

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

    Isso deve executar um console.log e, na resposta da ferramenta, você deve conseguir ver Hello World.

  • Validar que você pode instalar dependências e salvar arquivos

    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.

    Isso deve criar um arquivo no seu diretório montado (por exemplo, a Área de Trabalho) chamado "qrcode.png"

Uso com Claude Desktop

Adicione isto ao seu claude_desktop_config.json: Você pode seguir o Guia 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"
      ]
    }
  }
}

ou com 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: Certifique-se de que seu diretório de trabalho aponte para o servidor compilado e que o Docker esteja instalado/em execução.

Docker

Execute o servidor em um contêiner (monte o socket do Docker se necessário) e passe o diretório de saída desejado do host como uma variável de ambiente:

# 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

Isso faz o bind-mount da sua pasta do host no contêiner no mesmo caminho absoluto e disponibiliza FILES_DIR dentro do servidor MCP.

Uso efêmero – sem armazenamento persistente

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

Uso com VS Code

Botões de instalação rápida (VS Code & Insiders):

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

Configuração manual: Adicione ao seu settings.json ou .vscode/mcp.json do 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

Ferramentas

run_js_ephemeral

Execute um script JS único em um contêiner descartável totalmente novo.

Entradas:

  • image (string, opcional): Imagem Docker a ser usada (padrão: node:lts-slim).
  • code (string, obrigatório): Código-fonte JavaScript a ser executado.
  • dependencies (array de { name, version }, opcional): Pacotes e versões npm a serem instalados (padrão: []).

Comportamento:

  1. Cria um contêiner novo.
  2. Grava seu index.js e um package.json mínimo.
  3. Instala as dependências especificadas.
  4. Executa o script.
  5. Encerra (remove) o contêiner.
  6. Retorna o stdout capturado.
  7. Se o seu código salvar arquivos no diretório atual, esses arquivos serão retornados automaticamente.
    • Imagens (por exemplo, PNG, JPEG) são retornadas como conteúdo image.
    • Outros arquivos (por exemplo, .txt, .json) são retornados como conteúdo resource.
    • Nota: o recurso de salvamento de arquivos está disponível atualmente apenas na ferramenta efêmera.

Dica: Para obter os arquivos de volta, basta salvá-los durante a execução do script.

Exemplo de chamada:

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

Exemplo para salvar um arquivo:

import fs from 'fs/promises';

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

Isso retornará a saída do console e o arquivo hello.txt.

sandbox_initialize

Inicie um contêiner sandbox novo.

  • Entrada:
    • image (string, opcional, padrão: node:lts-slim): Imagem Docker para o sandbox
    • port (number, opcional): Se definido, mapeia esta porta do contêiner para o host
  • Saída: String com o ID do contêiner

sandbox_exec

Execute comandos shell dentro do sandbox em execução.

  • Entrada:
    • container_id (string): ID de sandbox_initialize
    • commands (string[]): Array de comandos shell a serem executados
  • Saída: stdout combinado de cada comando

run_js

Instale dependências npm e execute código JavaScript.

  • Entrada:

    • container_id (string): ID de sandbox_initialize
    • code (string): Código-fonte JS a ser executado (módulos ES suportados)
    • dependencies (array de { name, version }, opcional, padrão: []): nomes de pacotes npm → versões semver
    • listenOnPort (number, opcional): Se definido, mantém o processo em execução e expõe esta porta ao host (Modo Destacado)

  • Comportamento:

    1. Cria um workspace temporário dentro do contêiner
    2. Grava index.js e um package.json mínimo
    3. Executa npm install --omit=dev --ignore-scripts --no-audit --loglevel=error
    4. Executa node index.js e captura o stdout, ou deixa o processo em execução em segundo plano se listenOnPort estiver definido
    5. Limpa o workspace, a menos que esteja em modo destacado

  • Saída: stdout do script ou aviso de execução em segundo plano

sandbox_stop

Encerre e remova o contêiner sandbox.

  • Entrada:
    • container_id (string): ID de sandbox_initialize
  • Saída: Mensagem de confirmação

search_npm_packages

Pesquise pacotes npm por um termo de busca e obtenha nome, descrição e um trecho do README.

  • Entrada:

    • searchTerm (string, obrigatório): O termo a ser pesquisado nos pacotes npm. Deve conter todo o contexto relevante. Use sinais de mais (+) para combinar termos relacionados (por exemplo, "react+components" para bibliotecas de componentes React).
    • qualifiers (object, opcional): Qualificadores opcionais para filtrar os resultados da pesquisa:
      • author (string, opcional): Filtrar pelo nome do autor do pacote
      • maintainer (string, opcional): Filtrar pelo nome do mantenedor do pacote
      • scope (string, opcional): Filtrar pelo escopo npm (por exemplo, "@vue" para pacotes Vue.js)
      • keywords (string, opcional): Filtrar por palavras-chave do pacote
      • not (string, opcional): Excluir pacotes que correspondam a este critério (por exemplo, "insecure")
      • is (string, opcional): Incluir apenas pacotes que correspondam a este critério (por exemplo, "unstable")
      • boostExact (string, opcional): Reforçar correspondências exatas para este termo nos resultados da pesquisa

  • Comportamento:

    1. Pesquisa o registro npm usando o termo de busca e os qualificadores fornecidos
    2. Retorna até 5 pacotes ordenados por popularidade
    3. Para cada pacote, fornece nome, descrição e trecho do README (primeiros 500 caracteres)

  • Saída: Array JSON contendo detalhes dos pacotes com nome, descrição e trecho do README

Dicas de Uso

  • Ferramentas baseadas em sessão (sandbox_initialize ➔ run_js ➔ sandbox_stop) são ideais quando você quer:
    • Manter um contêiner sandbox de longa duração aberto.
    • Executar vários comandos ou scripts no mesmo ambiente.
    • Instalar e reutilizar dependências incrementalmente.
  • Execução única com run_js_ephemeral é perfeita para:
    • Experimentos rápidos ou scripts simples.
    • Casos em que você não precisa manter estado ou cache de dependências.
    • Execuções limpas e atômicas sem se preocupar com encerramento manual.
  • Modo destacado é útil quando você quer:
    • Iniciar servidores ou serviços de longa duração em tempo real
    • Expor e testar endpoints de contêineres em execução

Escolha o fluxo de trabalho que melhor se adapta ao seu caso de uso!

Build

Compile e empacote:

npm install
npm run build

Licença

Licença MIT

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que as pessoas a quem o Software for fornecido o façam, sujeito às seguintes condições:

O aviso de direitos autorais acima e este aviso de permissão devem ser incluídos em todas as cópias ou partes substanciais do Software.

O SOFTWARE É FORNECIDO "NO ESTADO EM QUE SE ENCONTRA", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIABILIDADE, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, ATO ILÍCITO OU DE OUTRA FORMA, DECORRENTE DE, OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.