Code Sandbox

You can run arbitrary JavaScript inside isolated, ephemeral Node.js sandboxes that install dependencies on demand. This MCP server starts a container, executes your code, captures stdout, and cleans up when finished, with options for long‑running detached mode if you need servers or persistent workspaces.

How to use

You connect to the MCP server from your client and submit tasks that run JavaScript in a fresh container. You can perform quick one‑off experiments where dependencies are installed automatically, or you can keep a sandbox alive to run multiple steps or a small server. Use one of the provided tooling flows to start a sandbox, run your code, and stop the sandbox when you are done.

How to install

Prerequisites: you need Docker installed and running on your machine.

Prepare your environment and connect a client that can talk to MCP (for example Claude Desktop). Then follow the concrete steps below to run the server using the two official MCP configurations shown.

# 1) Start the server as a Dockerized stdio MCP entry (example 1)
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

# 2) Alternatively, use NPX to run the stdio MCP locally
npx -y node-code-sandbox-mcp

Configuration and usage notes

You can configure the MCP client with multiple servers. The following examples demonstrate two explicit configurations shown for this MCP server. Use the one that matches your environment.

{
  "mcpServers": {
    "js_sandbox": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "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"
      ]
    },

    "node_code_sandbox": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-code-sandbox-mcp"],
      "env": {
        "FILES_DIR": "/Users/you/Desktop/node-sandbox",
        "SANDBOX_MEMORY_LIMIT": "512m",
        "SANDBOX_CPU_LIMIT": "0.75"
      }
    }
  }
}

Tools

This MCP server exposes a set of tools that you can call from your client to manage sandboxes and run JavaScript with optional dependencies. The primary tool endpoints and behaviors are described below.

- run_js_ephemeral: Run a one-off JS script in a brand-new disposable container. Returns stdout and any saved files.
- sandbox_initialize: Start a fresh sandbox container. Returns the container ID.
- sandbox_exec: Run shell commands inside the running sandbox. Returns combined stdout.
- run_js: Install dependencies and execute JavaScript inside a sandbox, with optional detached mode.
- sandbox_stop: Terminate and remove the sandbox container.

Usage tips

Use session‑based tools when you want to reuse a single sandbox across multiple steps, install dependencies incrementally, or keep a long‑running environment. Use ephemeral one‑shot tooling for quick experiments where you do not need to maintain state afterward. Detached mode is ideal for long‑running services that you want to test from a running container.

Build

To build and bundle the MCP server, run the following commands in sequence.

npm install
npm run build

License

MIT License. The software is provided without warranty of any kind. You may obtain a copy of the license with the project files.

Available tools

run_js_ephemeral

Run a one-off JavaScript script in a brand-new disposable container, with optional dependencies and saved files returned.

sandbox_initialize

Start a fresh sandbox container that will host subsequent code execution.

sandbox_exec

Run shell commands inside the running sandbox to perform setup or ad-hoc tasks.

run_js

Install npm dependencies, write a workspace, and execute JavaScript code within the sandbox, with optional detached mode for long-running processes.

sandbox_stop

Terminate and remove the sandbox container to clean up resources.