Labsco
alfonsograziano logo

Node.js Sandbox MCP Server

★ 152

from alfonsograziano

Run arbitrary JavaScript in an isolated Docker container with on-the-fly npm dependency installation.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#scraping#devops

🐢🚀 Node.js Sandbox MCP Server

Node.js server implementing the Model Context Protocol (MCP) for running arbitrary JavaScript in ephemeral Docker containers with on‑the‑fly npm dependency installation.

Website Preview

👉 Look at the official website

📦 Available on Docker Hub

Features

  • Start and manage isolated Node.js sandbox containers
  • Execute arbitrary shell commands inside containers
  • Install specified npm dependencies per job
  • Run ES module JavaScript snippets and capture stdout
  • Tear down containers cleanly
  • Detached Mode: Keep the container alive after script execution (e.g. for long-running servers)

Note: Containers run with controlled CPU/memory limits.

Explore Cool Use Cases

If you want ideas for cool and powerful ways to use this library, check out the use cases section on the website It contains a curated list of prompts, examples, and creative experiments you can try with the Node.js Sandbox MCP Server.

API

Tools

run_js_ephemeral

Run a one-off JS script in a brand-new disposable container.

Inputs:

  • image (string, optional): Docker image to use (default: node:lts-slim).
  • code (string, required): JavaScript source to execute.
  • dependencies (array of { name, version }, optional): NPM packages and versions to install (default: []).

Behavior:

  1. Creates a fresh container.
  2. Writes your index.js and a minimal package.json.
  3. Installs the specified dependencies.
  4. Executes the script.
  5. Tears down (removes) the container.
  6. Returns the captured stdout.
  7. If your code saves any files in the current directory, these files will be returned automatically.
    • Images (e.g., PNG, JPEG) are returned as image content.
    • Other files (e.g., .txt, .json) are returned as resource content.
    • Note: the file saving feature is currently available only in the ephemeral tool.

Tip: To get files back, simply save them during your script execution.

Example Call:

{
  "name": "run_js_ephemeral",
  "arguments": {
    "image": "node:lts-slim",
    "code": "console.log('One-shot run!');",
    "dependencies": [{ "name": "lodash", "version": "^4.17.21" }],
  },
}

Example to save a file:

import fs from 'fs/promises';

await fs.writeFile('hello.txt', 'Hello world!');
console.log('Saved hello.txt');

This will return the console output and the hello.txt file.

sandbox_initialize

Start a fresh sandbox container.

  • Input:
    • image (string, optional, default: node:lts-slim): Docker image for the sandbox
    • port (number, optional): If set, maps this container port to the host
  • Output: Container ID string

sandbox_exec

Run shell commands inside the running sandbox.

  • Input:
    • container_id (string): ID from sandbox_initialize
    • commands (string[]): Array of shell commands to execute
  • Output: Combined stdout of each command

run_js

Install npm dependencies and execute JavaScript code.

  • Input:

    • container_id (string): ID from sandbox_initialize
    • code (string): JS source to run (ES modules supported)
    • dependencies (array of { name, version }, optional, default: []): npm package names → semver versions
    • listenOnPort (number, optional): If set, leaves the process running and exposes this port to the host (Detached Mode)

  • Behavior:

    1. Creates a temp workspace inside the container
    2. Writes index.js and a minimal package.json
    3. Runs npm install --omit=dev --ignore-scripts --no-audit --loglevel=error
    4. Executes node index.js and captures stdout, or leaves process running in background if listenOnPort is set
    5. Cleans up workspace unless running in detached mode

  • Output: Script stdout or background execution notice

sandbox_stop

Terminate and remove the sandbox container.

  • Input:
    • container_id (string): ID from sandbox_initialize
  • Output: Confirmation message

search_npm_packages

Search for npm packages by a search term and get their name, description, and a README snippet.

  • Input:

    • searchTerm (string, required): The term to search for in npm packages. Should contain all relevant context. Use plus signs (+) to combine related terms (e.g., "react+components" for React component libraries).
    • qualifiers (object, optional): Optional qualifiers to filter the search results:
      • author (string, optional): Filter by package author name
      • maintainer (string, optional): Filter by package maintainer name
      • scope (string, optional): Filter by npm scope (e.g., "@vue" for Vue.js packages)
      • keywords (string, optional): Filter by package keywords
      • not (string, optional): Exclude packages matching this criteria (e.g., "insecure")
      • is (string, optional): Include only packages matching this criteria (e.g., "unstable")
      • boostExact (string, optional): Boost exact matches for this term in search results

  • Behavior:

    1. Searches the npm registry using the provided search term and qualifiers
    2. Returns up to 5 packages sorted by popularity
    3. For each package, provides name, description, and README snippet (first 500 characters)

  • Output: JSON array containing package details with name, description, and README snippet

Build

Compile and bundle:

npm install
npm run build