Node.js MCP Server: Docker Sandboxes with On-the-Fly npm

Overview

This MCP (Model Context Protocol) server provides a lightweight way to execute JavaScript snippets inside isolated Docker sandboxes with on-the-fly npm package resolution. It is designed for integrations where language models or other automation workflows need to execute code securely and reproducibly without persisting packages or environments between runs.

The server creates ephemeral containers per execution request, installs only the npm packages required by the snippet, runs the code, collects stdout/stderr, and returns the results via an MCP-compatible API. The sandboxed approach keeps host exposure minimal (resource limits, network/volume restrictions) while allowing quick, repeatable experiments with third-party npm modules.

Features

• Ephemeral Docker sandboxes for each execution request
• On-demand npm installation scoped to the sandbox (package.json or package list)
• MCP-compatible HTTP endpoints to create, run, and stop sandboxes
• Execution timeouts and memory/CPU limits
• Optional caching of npm artifacts to speed up repeated installs
• JSON result payloads containing stdout, stderr, exit code, and package install logs
• Simple integration examples for server-side or model-driven workflows

Installation / Configuration

Prerequisites:

• Docker Engine
• Node.js (>= 16)
• Git

Clone and install:

git clone https://github.com/alfonsograziano/node-code-sandbox-mcp.git
cd node-code-sandbox-mcp
npm install

Environment variables (example .env):

PORT=3000
SANDBOX_IMAGE=node:18-bullseye
SANDBOX_TIMEOUT_MS=10000      # time limit for execution in ms
SANDBOX_MEMORY_LIMIT=256m     # docker memory limit
SANDBOX_CPU_SHARES=512        # docker cpu shares
NPM_CACHE_DIR=/tmp/npm-cache  # optional host cache for speed
ALLOW_NETWORK=false           # whether sandboxes may access the network

Start the server:

# using npm scripts
npm run start

# or with environment file
PORT=3000 node server.js

If you prefer Docker for the server itself, build and run:

docker build -t mcp-sandbox-server .
docker run -p 3000:3000 --env-file .env mcp-sandbox-server

Common environment variables

Available Resources

• GitHub repository: https://github.com/alfonsograziano/node-code-sandbox-mcp
• Included: example templates for package.json, a set of utility scripts to create/teardown containers, and MCP route handlers
• Tools: Docker (required), Node.js runtime inside sandboxes, npm for on-the-fly package installs
• Example client snippets (see Use Cases) for invoking the MCP endpoints

API (typical endpoints)

The server exposes REST endpoints compatible with MCP-style usage. Exact route names may vary; adapt them to your deployment.

• POST /sandbox/create — create a new sandbox (returns sandbox id)
• POST /sandbox/:id/run — run code in a sandbox; body can include code, packages, and packageJson
• POST /sandbox/:id/stop — stop and remove a sandbox
• GET /sandbox/:id/status — get status and logs

Example request body for /sandbox/:id/run:

{
  "code": "const _ = require('lodash'); console.log(_.kebabCase('Hello World'));",
  "packages": ["[email protected]"],
  "timeoutMs": 5000
}

Response payload includes:

• stdout (string)
• stderr (string)
• exitCode (number)
• installLog (string)
• elapsedMs (number)

Use Cases

1. Model-driven code execution

   • A language model generates a JavaScript snippet that requires a third-party module. Send the snippet and a list of npm packages to the MCP server; it will install only what’s needed and run the snippet in an isolated container, returning the output and any errors.

2. Interactive playgrounds / REPLs

   • Build a web-based REPL where each user execution runs in a fresh sandbox. On-the-fly npm enables users to try packages without polluting a shared environment.

3. Safe evaluation for learning platforms

   • Run student-submitted code with strict time and memory limits to prevent resource abuse. Capture stdout and stderr for grading or feedback.

4. Test harness for snippets

   • Execute unit-test snippets or sample code against a controlled environment. Use package caching to speed up repeated test runs.

Example curl call:

curl -X POST http://localhost:3000/sandbox/create -H "Content-Type: application/json" -d '{}'
# returns { "id": "sandbox-abc123" }

curl -X POST http://localhost:3000/sandbox/sandbox-abc123/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "const axios = require(\"axios\"); (async ()=>{ const r = await axios.get(\"https://api.github.com\"); console.log(r.status) })();",
    "packages": ["axios@1"]
  }'

Security notes

• The server runs code in ephemeral containers with configurable limits; however, always assume risk when executing untrusted code.
• Use ALLOW_NETWORK=false to prevent outbound network access, mount only required volumes, and run sandbox images with reduced privileges.
• Monitor and enforce timeouts and resource quotas.

This MCP server offers a straightforward pattern to run JavaScript snippets securely while allowing dynamic dependency resolution. It’s especially useful when models or services must evaluate or test code that relies on npm packages without long-lived environments.