AI导哈

Node.js沙箱服务器

实现Model Context Protocol (MCP)的Node.js服务器，用于在临时Docker容器中运行任意JavaScript代码并动态安装npm依赖。

  • by ssdeanx
  • TypeScript
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 ssdeanx/node-code-sandbox-mcp

使用说明

🐢🚀 Node.js沙盒MCP服务器

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

👉 查看官方网站

特性

  • 启动和管理隔离的Node.js沙箱容器
  • 在容器内执行任意shell命令
  • 为每个作业安装指定的npm依赖项
  • 运行ES模块JavaScript代码段并捕获stdout
  • 干净地拆下容器
  • 分离模式： 在脚本执行后保持容器活动（例如，对于长时间运行的服务器）

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

探索酷炫的用例

如果你想了解使用这个库的酷而强大的方法，请查看 网站上的用例部分 它包含一个精心策划的提示、示例和创意实验列表，您可以使用Node.js Sandbox MCP Server进行尝试。

⚠️ 先决条件

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

提示： 预拉取你需要的任何Docker镜像，以避免第一次执行时的延迟。

推荐图片示例：

  • 节点：lts slim
  • 微软/剧作家：v1.52.0-noble
  • alfonsograziano/node chartjs画布：最新

入门

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

运行后，您可以通过几个测试提示来测试它是否完全工作：

  • 验证该工具是否可以运行：

    Create and run a JS script with a console.log("Hello World")

    这应该会运行一个console.log，在工具响应中，您应该能够看到Hello World。

  • 验证您是否可以安装依赖项并保存文件

    Create and run a JS script that generates a QR code for the URL `https://nodejs.org/en`, and save it as `qrcode.png` **Tip:** Use the `qrcode` package.

    这应该会在您挂载的目录（例如Desktop）中创建一个名为“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", // optional
        "-e",
        "SANDBOX_CPU_LIMIT=0.75", // optional
        "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", // optional
        "SANDBOX_CPU_LIMIT": "0.75" // optional
      }
    }
  }
}

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

码头工人

在容器中运行服务器（如果需要，可以挂载Docker套接字），并将所需的主机输出目录作为env-var传递：

# Build locally if necessary
# 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

此绑定将您的主机文件夹装载到以下位置的容器中 相同的绝对路径 并使 FILES_DIR MCP服务器内部可用。

使用VS代码

快速安装 按钮（VS代码和内部人员）：

安装js沙盒mcp（NPX）安装js沙盒mcp（Docker）

手动配置：添加到您的VS代码 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_临时

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

输入：

  • image （string，可选）：要使用的Docker镜像（默认值： node:lts-slim).
  • code （string，必填）：要执行的JavaScript源代码。
  • dependencies （数组 { name, version }，可选）：要安装的NPM包和版本（默认值： []).

行为：

  1. 创建新容器。
  2. 写你的 index.js 以及最小值 package.json.
  3. 安装指定的依赖项。
  4. 执行脚本。
  5. 撕下（取出）容器。
  6. 返回捕获的stdout。
  7. 如果您的代码在当前目录中保存了任何文件，这些文件将自动返回。
    • 图像（例如PNG、JPEG）返回为 image 内容。
    • 其他文件（例如。， .txt, .json)返回为 resource 内容。
    • 注意：文件保存功能目前仅在临时工具中可用。

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

呼叫示例：

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

保存文件的示例：

import fs from 'fs/promises';

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

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

沙盒初始化

启动一个新的沙盒容器。

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

沙盒exec

在正在运行的沙盒中运行shell命令。

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

run_js

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

  • 输入:

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

  • 行为：

    1. 在容器内创建临时工作区
    2. 写入 index.js 以及最小值 package.json
    3. 跑 npm install --omit=dev --ignore-scripts --no-audit --loglevel=error
    4. 执行 node index.js 并捕获stdout，或者在以下情况下让进程在后台运行 listenOnPort 已设置
    5. 清理工作区，除非在分离模式下运行

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

沙盒停止

终止并删除沙盒容器。

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

使用技巧

  • 基于会话的工具 (sandbox_initialize ➔ run_js ➔ sandbox_stop)当你想：
    • 保持长期沙盒容器打开。
    • 在同一环境中运行多个命令或脚本。
    • 逐步安装和重用依赖项。
  • 一枪处决 随着 run_js_ephemeral 非常适合：
    • 快速实验或简单脚本。
    • 不需要维护状态或缓存依赖关系的情况。
    • 清洁、原子运行，无需担心手动拆卸。
  • 分离模式 当您想要：
    • 动态启动服务器或长期服务
    • 从正在运行的容器中暴露和测试端点

选择最适合您用例的工作流！

构建

编译和捆绑：

npm install
npm run build

许可证

MIT许可证

特此免费授予任何获得本软件和相关文档文件（“软件”）副本的人在不受限制的情况下处理软件的权限，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，以及允许获得软件的人这样做，但须符合以下条件：

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

软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下，作者或版权持有人均不对任何索赔承担责任， 因软件引起的或与软件有关的损害赔偿或其他责任，无论是在合同、侵权或其他诉讼中 或软件的使用或其他交易。

相关 MCP