Node Code Sandbox MCP

What alfonsograziano/node-code-sandbox-mcp MCP server does

The alfonsograziano/node-code-sandbox-mcp MCP server gives an MCP client a way to run JavaScript in Docker-backed Node.js environments. It can create a disposable container for a single script or maintain a container across several operations. Scripts use ES modules, can install npm dependencies specified as package-and-version pairs, and return captured standard output.

The ephemeral execution path also returns files created in the script's working directory. Image files such as PNG and JPEG files are returned as image content, while other files such as text or JSON are returned as resources. This supports tasks such as generating an artifact with a Node package and sending the result back through the tool response.

How it works

A one-shot request selects a Docker image, supplies JavaScript source, and optionally lists npm dependencies. The server creates a new container, writes an entry script and minimal package metadata, installs the requested packages, runs the code, captures stdout, and removes the container afterward.

For longer workflows, sandbox_initialize creates a container and returns its ID. sandbox_exec runs one or more shell commands in that container. run_js creates a temporary workspace, installs dependencies with npm using production-only, script-disabled, audit-disabled settings, and runs the supplied ES module. A listenOnPort value changes this behavior: the process remains in the background and the selected port is exposed to the host. sandbox_stop terminates and removes the container.

The server supports resource controls through memory and CPU settings. Docker images can be selected per sandbox, with node:lts-slim used by default. A port can be mapped when initializing a sandbox.

Setup and configuration

Docker must be installed and running before the alfonsograziano/node-code-sandbox-mcp MCP server can execute jobs. The documented NPX configuration runs node-code-sandbox-mcp with npx -y. A Docker-based MCP configuration instead runs the mcp/node-code-sandbox image and mounts /var/run/docker.sock so the server can create child containers.

FILES_DIR can identify a host directory for generated files. The directory is mounted into the server container in the Docker configuration examples. SANDBOX_MEMORY_LIMIT and SANDBOX_CPU_LIMIT configure optional container resource limits. Pre-pulling the images used for jobs can reduce first-run delays.

Tools and capabilities

• run_js_ephemeral: execute JavaScript in a new disposable container and receive stdout plus files created by the script.
• sandbox_initialize: start a reusable sandbox and return its container ID.
• sandbox_exec: execute shell commands in an existing sandbox.
• run_js: install selected npm packages and run JavaScript in an existing sandbox, with optional detached mode and port exposure.
• sandbox_stop: stop and remove a sandbox by container ID.

Limitations and notes

The server depends on Docker and requires access to the Docker socket when it is itself run in a container. Dependency installation occurs during execution, so network access and npm availability affect jobs that request packages. Detached processes are not cleaned up with the temporary workspace; callers should stop the associated container when it is no longer needed.