🐢🚀 Node.js Sandbox MCP 服务器

实现模型上下文协议（MCP）的Node.js服务器，用于在临时Docker容器中运行任意JavaScript，并即时安装npm依赖。

👉 查看官方网站

特性

• 启动并管理隔离的Node.js沙箱容器
• 在容器内执行任意shell命令
• 按任务安装指定的npm依赖
• 运行ES模块JavaScript片段并捕获标准输出
• 清洁地销毁容器
• 分离模式： 脚本执行后保持容器存活（例如，用于长时间运行的服务器）

注意：容器以受控的CPU/内存限制运行。

探索酷炫用例

如果你想要一些有趣且强大的使用方法，请查看网站上的用例部分。它包含了一个精心挑选的提示、示例和创意实验列表，你可以尝试使用Node.js沙箱MCP服务器。

⚠️ 先决条件

要使用此MCP服务器，您的机器上必须已安装并运行Docker。

提示： 预先拉取您需要的任何Docker镜像，以避免首次执行时出现延迟。

推荐的镜像示例：

• node:lts-slim
• mcr.microsoft.com/playwright:v1.52.0-noble
• alfonsograziano/node-chartjs-canvas:latest

快速开始

为了开始使用这个MCP服务器，首先你需要将其连接到客户端（例如Claude Desktop）。

一旦运行起来，你可以通过几个测试提示来验证其是否完全正常工作：

• 验证工具能否运行：

  创建并运行一个带有console.log("Hello World")的JS脚本
  

  这应该运行一个console.log，并在工具响应中可以看到“Hello World”。

• 验证能否安装依赖并保存文件

  创建并运行一个生成URL `https://nodejs.org/en` 的二维码的JS脚本，并将其保存为`qrcode.png` **提示：** 使用`qrcode`包。
  

  这应该在挂载的目录（例如桌面）中创建一个名为“qrcode.png”的文件。

与Claude Desktop一起使用

将以下内容添加到您的claude_desktop_config.json中： 您可以按照官方指南来安装这个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", // 可选
        "alfonsograziano/node-code-sandbox-mcp"
      ]
    }
  }
}

或使用NPX：

{
  "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" // 可选
      }
    }
  }
}

注意：确保您的工作目录指向构建好的服务器，并且已经安装并运行了Docker。

Docker

在容器中运行服务器（如果需要，挂载Docker套接字），并通过环境变量传递您希望的主机输出目录：

# 如果有必要，本地构建
# docker build -t alfonsograziano/node-code-sandbox-mcp .

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

这将把您的主机文件夹绑定挂载到容器中的相同绝对路径，并在MCP服务器内部使FILES_DIR可用。

与VS Code一起使用

快速安装按钮（VS Code & Insiders）：

安装js-sandbox-mcp (NPX) 安装js-sandbox-mcp (Docker)

手动配置：添加到您的VS Code settings.json 或 .vscode/mcp.json：

"mcp": {
    "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",
                "alfonsograziano/node-code-sandbox-mcp"
              ]
        }
    }
}

API

工具

run_js_ephemeral

在一个全新的可丢弃容器中运行一次性JS脚本。

输入：

• image (字符串，可选)：使用的Docker镜像（默认：node:lts-slim）。
• code (字符串，必需)：要执行的JavaScript源代码。
• dependencies (数组，可选)：NPM包及其版本（默认：[]）。

行为：

1. 创建一个新的容器。
2. 写入您的index.js和最小的package.json。
3. 安装指定的依赖项。
4. 执行脚本。
5. 销毁（移除）容器。
6. 返回捕获的标准输出。
7. 如果您的代码在当前目录中保存了任何文件，这些文件将自动返回。
   • 图像（如PNG、JPEG）作为image内容返回。
   • 其他文件（如.txt、.json）作为resource内容返回。
   • 注意：文件保存功能目前仅在临时工具中可用。

提示： 若要获取文件，只需在脚本执行期间保存它们即可。

示例调用：

{
  "name": "run_js_ephemeral",
  "arguments": {
    "image": "node:lts-slim",
    "code": "console.log('一次性运行！');",
    "dependencies": [{ "name": "lodash", "version": "^4.17.21" }],
  },
}

保存文件的示例：

import fs from 'fs/promises';

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

这将返回控制台输出以及hello.txt文件。

sandbox_initialize

启动一个新的沙箱容器。

• 输入：
  • image (字符串，可选，默认：node:lts-slim)：沙箱的Docker镜像
  • port (数字，可选)：如果设置，则将此容器端口映射到主机
• 输出：容器ID字符串

sandbox_exec

在正在运行的沙箱中执行shell命令。

• 输入：
  • container_id (字符串)：来自sandbox_initialize的ID
  • commands (字符串数组)：要执行的shell命令数组
• 输出：每个命令的组合标准输出

run_js

安装npm依赖项并执行JavaScript代码。

• 输入：

  • container_id (字符串)：来自sandbox_initialize的ID
  • code (字符串)：要运行的JS源代码（支持ES模块）
  • dependencies (数组，可选，默认：[])：npm包名 → semver版本
  • listenOnPort (数字，可选)：如果设置，则让进程在后台运行并暴露此端口给主机（分离模式）

• 行为：

  1. 在容器内创建一个临时工作区
  2. 写入index.js和最小的package.json
  3. 运行npm install --omit=dev --ignore-scripts --no-audit --loglevel=error
  4. 执行node index.js并捕获标准输出，或者如果设置了listenOnPort则让进程在后台运行
  5. 除非处于分离模式，否则清理工作区

• 输出：脚本标准输出或后台执行通知

sandbox_stop

终止并移除沙箱容器。

• 输入：
  • container_id (字符串)：来自sandbox_initialize的ID
• 输出：确认消息

使用技巧

• 基于会话的工具（sandbox_initialize ➔ run_js ➔ sandbox_stop）非常适合以下情况：
  • 保持长时间运行的沙箱容器打开。
  • 在同一环境中运行多个命令或脚本。
  • 逐步安装并重复使用依赖项。
• 一次性执行使用run_js_ephemeral非常适合：
  • 快速实验或简单的脚本。
  • 不需要维护状态或缓存依赖项的情况。
  • 清晰、原子化的运行，无需担心手动清理。
• 分离模式在以下情况下非常有用：
  • 即时启动服务器或长时间运行的服务
  • 从运行的容器中暴露并测试端点

选择最适合您使用场景的工作流程！

构建

编译和打包：

npm install
npm run build

许可证

MIT许可证

特此授予任何人获得该软件及关联文档文件（以下简称“软件”）副本的权利，无限制地处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，以及向他们提供软件的人做同样的事情，但需遵守以下条件：

上述版权声明和本许可通知应包含在软件的所有副本或实质性部分中。

软件按“原样”提供，不附带任何形式的担保，无论是明示的还是默示的，包括但不限于对适销性、特定用途适用性和非侵权性的担保。在任何情况下，作者或版权持有者均不对因软件或与软件的使用或其他交易相关的任何索赔、损害或其他责任负责，无论是在合同、侵权行为或其他情况下。