Node.js Sandbox MCP Server

How to use

Connect your MCP-enabled client to the Node.js Sandbox MCP Server and start by creating a fresh sandbox instance. You then install any npm dependencies you need for your task, write and run JavaScript, and capture stdout or save files back to your host. You can run quick one‑offs that terminate after completion or run in detached mode to keep the sandbox alive for longer operations.

How to install

Prerequisites you need on your machine: install and run Docker, and ensure your user has permission to run docker commands.

1) Build or pull the MCP server image if you need a local image. The server can be run directly via Docker as shown.

2) Run the server in a container and mount a host directory for outputs. Use an output directory on the host and expose it inside the container as /root.

3) Choose a working directory for your projects and ensure Docker is running.

Configuration and usage examples

{
  "mcpServers": {
    "js_sandbox": {
      "type": "stdio",
      "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",
        "-e",
        "SANDBOX_CPU_LIMIT=0.75",
        "mcp/node-code-sandbox"
      ]
    }
  }
}

Saving output files from a script

If your script saves files in the current directory, those files are returned to you automatically. Images are delivered as image content, and other files are delivered as resource content. Save files during script execution to retrieve them later.

Tools you can use with this MCP server

run_js_ephemeral — Run a one-off JS script in a brand-new disposable container. It optionally installs npm dependencies and returns stdout, and can also return any files you saved during execution.

Important server commands you will use

sandbox_initialize — Start a fresh sandbox container and return a container ID.

sandbox_exec — Run shell commands inside the running sandbox and return the combined stdout.

run_js — Install npm dependencies, write an index.js and a minimal package.json, run the script, capture stdout, and optionally detach to keep the process running and expose a host port.

sandbox_stop — Terminate and remove the sandbox container.

search_npm_packages — Search npm for packages matching a term and return name, description, and a README snippet.

Usage with a client (example workflows)

Session-based workflow: initialize a sandbox, run multiple commands or scripts in the same environment, install dependencies progressively, and stop the sandbox when finished.

One-shot workflow: perform quick experiments or simple scripts without maintaining state. The container is removed after execution.

Detached mode: keep a sandbox running for long‑running tasks or servers and test endpoints from the host.

Notes on security and behavior

Containers run with controlled CPU and memory limits to protect your host system. Use sandbox environment variables to adjust limits as needed.

run_js_ephemeral

Run a one-off JavaScript snippet in a brand-new disposable container, install optional npm dependencies, capture stdout, and return any saved files