node-code-sandbox

This MCP server provides a Node.js sandbox that runs JavaScript in ephemeral Docker containers with on-the-fly npm dependency installation. You can spawn isolated sandboxes, execute JS snippets (including ES modules), install dependencies per job, and capture stdout and any files saved during execution. The tool supports both ephemeral one-off runs and long-running, detached execution where the container remains alive after a script finishes. Typical workflows involve initializing a sandbox, running your JS code (with optional npm dependencies), and then tearing down or reusing the sandbox as needed. Use the provided APIs to run code, install dependencies, and (optionally) retrieve produced files from the mounted host directory.

Prerequisites:

• Docker must be installed and running on your machine.
• Node.js/npm or NPX must be available if you plan to use the NPX-based startup.

Installation options:

Option A: NPX (recommended for quick start)

1. Ensure Node.js is installed (Node.js 14+ recommended).
2. Run the MCP server via NPX:

npx -y node-code-sandbox-mcp

3. When prompted, configure environment variables as needed (e.g., FILES_DIR for mounted output, optional SANDBOX memory/CPU limits).

Option B: Docker (self-contained environment)

1. Build or pull the image:

# Build locally if you have a Dockerfile
# docker build -t alfonsograziano/node-code-sandbox-mcp .

2. Run the container, mounting an output directory and exposing environment vars:

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" \
  alfonsograziano/node-code-sandbox-mcp stdio

3. The container will start in stdio mode and listen for MCP commands via the configured channel.

Prerequisites summary: Docker installed and running; Node.js/npm for NPX usage; optionally pre-pull necessary Docker images for faster startup.

Tips and notes:

• The SANDBOX_MEMORY_LIMIT and SANDBOX_CPU_LIMIT environment variables are optional but recommended to prevent resource exhaustion when running untrusted code.
• When using the Docker route, the server typically binds the host output directory to /root (as FILES_DIR) so any files saved by the JS code can be retrieved on the host.
• For NPX usage, ensure the working directory contains any needed server files or dependencies; NPX will fetch the package on demand.
• If you plan to reuse a sandbox for long-running tasks, consider enabling Detached Mode to keep the container alive after script execution.
• Common issues: missing Docker socket permissions, insufficient host directory permissions, or network restrictions preventing npm install inside the sandbox.
• If you encounter permission errors, ensure the user running Docker has appropriate access to the Docker socket and the mounted host directory.