MCP Directory

How to add Node.js Sandbox MCP Server to Windsurf

Run arbitrary JavaScript in ephemeral Docker containers with on-the-fly npm dependency installation. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 152★ · stdio · no auth

Windsurf config for Node.js Sandbox MCP Server

npx -y node-code-sandbox-mcp
{
  "mcpServers": {
    "node-js-sandbox-mcp-server": {
      "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"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Node.js Sandbox MCP Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Node.js Sandbox MCP Server's tools become available to Cascade.

Before you start

  • Docker installed and running on the host machine
  • Recommended: pre-pull Docker images such as node:lts-slim, mcr.microsoft.com/playwright:v1.55.0-noble, and alfonsograziano/node-chartjs-canvas:latest

What Node.js Sandbox MCP Server can do in Windsurf

run_js_ephemeral

Run a one-off JS script in a brand-new disposable container. Creates a fresh container, writes index.js and a minimal package.json, installs the specified dependencies, executes the script, tears down the container, and returns captured stdout. Any files saved during execution are returned automatically (images as image content, others as resource content). Inputs: image (optional, default node:lts-slim), code (required), dependencies (optional array of { name, version }).

sandbox_initialize

Start a fresh sandbox container. Inputs: image (optional, default node:lts-slim), port (optional, maps a container port to the host). Output: container ID string.

sandbox_exec

Run shell commands inside the running sandbox. Inputs: container_id (from sandbox_initialize), commands (array of shell commands). Output: combined stdout of each command.

run_js

Install npm dependencies and execute JavaScript code in a running container. Inputs: container_id, code (ES modules supported), dependencies (optional array of { name, version }), listenOnPort (optional; leaves the process running and exposes the port to the host in Detached Mode). Output: script stdout or background execution notice.

sandbox_stop

Terminate and remove the sandbox container. Input: container_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. Inputs: searchTerm (required), qualifiers (optional: author, maintainer, scope, keywords, not, is, boostExact). Returns up to 5 packages sorted by popularity, each with name, description, and first 500 characters of the README.

Security

Executes arbitrary JavaScript and shell commands inside Docker containers. The recommended configuration mounts the Docker socket (/var/run/docker.sock) into the server container, which grants broad control over the host Docker daemon. Containers run with controlled CPU/memory limits (configurable via SANDBOX_MEMORY_LIMIT and SANDBOX_CPU_LIMIT). Docker must be installed and running on the host.

Node.js Sandbox MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Node.js Sandbox MCP Server config there under the "mcpServers" key and restart the client.

Is Node.js Sandbox MCP Server safe to use with Windsurf?

Executes arbitrary JavaScript and shell commands inside Docker containers. The recommended configuration mounts the Docker socket (/var/run/docker.sock) into the server container, which grants broad control over the host Docker daemon. Containers run with controlled CPU/memory limits (configurable via SANDBOX_MEMORY_LIMIT and SANDBOX_CPU_LIMIT). Docker must be installed and running on the host.

What do I need to run this server?

Docker must be installed and running on your machine. It is recommended to pre-pull any Docker images you'll need (e.g. node:lts-slim) to avoid delays during first execution.

How do I get generated files back?

Simply save files during your script execution. In the run_js_ephemeral tool, images (PNG, JPEG) are returned as image content and other files (.txt, .json) as resource content. The file saving feature is currently available only in the ephemeral tool.

Can I run a long-lived server inside the sandbox?

Yes. Use run_js with the listenOnPort input (Detached Mode) to leave the process running and expose the port to the host, which is useful for spinning up servers or testing endpoints.

View repo Full Node.js Sandbox MCP Server page