MCP SERVERRun the JavaScript a model just wrote inside a throwaway Docker container — one-shot or in a session you keep alive — with npm dependencies installed and files landing in a mounted directory.
LABSCO SUMMARY
The first decision is the shape: one-shot costs a container start on every call, while the initialise, run, stop cycle keeps installed dependencies and files between runs and leaves a container alive until it is stopped on purpose. get_dependency_types is the unusual member of the set — pulling .d.ts text before generating code against an unfamiliar package removes a whole class of confident wrong guesses. Everything rests on a working Docker daemon; there is no alternative execution path in the tool set if containers are unavailable.
A code-execution server that starts Node.js containers on the local Docker daemon, either as a disposable one-shot or as a session you initialise, reuse and stop.
A local Docker daemon the server can start containers on, and an image for it to run. Code must be valid ES modules using import and export, and anything read or written from the sandbox goes through the ./files directory. A session opened with sandbox_initialize keeps its container running until sandbox_stop is called.
One command — npx -y node-code-sandbox-mcp
USE CASES
Send the code to a disposable container with whatever npm packages it imports, read what it printed, and let the container clean itself up afterwards.
Find the package by search term, pull its type definitions to see what it actually exposes, and only then write and run code against it.
Start a container once, run successive versions of the code inside it without paying for a fresh install each time, drop to the shell when something needs inspecting, and stop it when the work is done.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_dependency_typesGiven an array of npm package names (and optional versions), fetch whether each package ships its own TypeScript definitions or has a corresponding @types/… package, and return the raw .d.ts text.
Useful whenwhen you're about to run a Node.js script against an unfamiliar dependency and want to inspect what APIs and types it exposes.
run_jsInstall npm dependencies and run JavaScript code inside a running sandbox container. After running, you must manually stop the sandbox to free resources. The code must be valid ESModules (import/export syntax). Best for complex workflows where you want to reuse the environment across multiple executions. When reading and writing from the Node.js processes, you always need to read from and write to the "./files" directory to ensure persistence on the mounted volume.
run_js_ephemeralRun a JavaScript snippet in a temporary disposable container with optional npm dependencies, then automatically clean up. The code must be valid ESModules (import/export syntax). Ideal for simple one-shot executions without maintaining a sandbox or managing cleanup manually. When reading and writing from the Node.js processes, you always need to read from and write to the "./files" directory to ensure persistence on the mounted volume. This includes images (e.g., PNG, JPEG) and other files (e.g., text, JSON, binaries).
Example:
import fs from "fs/promises";
await fs.writeFile("./files/hello.txt", "Hello world!");
console.log("Saved ./files/hello.txt");sandbox_execExecute one or more shell commands inside a running sandbox container. Requires a sandbox initialized beforehand.
sandbox_initializeStart a new isolated Docker container running Node.js. Used to set up a sandbox session for multiple commands and scripts.
sandbox_stopTerminate and remove a running sandbox container. Should be called after finishing work in a sandbox initialized with sandbox_initialize.
search_npm_packagesSearch for npm packages by a search term and get their name, description, and a README snippet.
BEFORE YOU INSTALL
7 tools when we connected. get_dependency_types is available but undocumented; the documentation covers the other six.
Docker installed and running on your machine
All 3 documented setups run the server on your machine.
CONTEXT COST
Rated by the size of the 7 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
npx -y node-code-sandbox-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",
"-e",
"SANDBOX_CPU_LIMIT=0.75",
"mcp/node-code-sandbox"
]
}
}
}Claude Desktop starts docker without a shell, so $HOME reaches Docker as literal text and the mount fails. Both $HOME/Desktop/sandbox-output values have to be the full path of a folder on your machine. SANDBOX_MEMORY_LIMIT and SANDBOX_CPU_LIMIT are optional.
{
"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",
"SANDBOX_CPU_LIMIT": "0.75"
}
}
}
}Set FILES_DIR to a folder on your own machine: /Users/alfonsograziano/Desktop/node-sandbox is the author's. Docker still has to be installed and running for this route. SANDBOX_MEMORY_LIMIT and SANDBOX_CPU_LIMIT are optional.
{
"servers": {
"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",
"-e",
"SANDBOX_CPU_LIMIT=1",
"mcp/node-code-sandbox"
]
}
}
}VS Code passes $HOME to docker as literal text. Both $HOME/Desktop/sandbox-output values have to be the full path of a folder on your machine; the README marks those two -v and -e pairs optional, so they can also go.
MCP servers
yepcode
JohanLi233
Tsuchijo
302ai