🐢🚀 Node.js Sandbox MCP Server

🐢🚀 Node.js Sandbox MCP 服务

用于实现 Model Context Protocol（MCP）的 Node.js 服务，可在临时 Docker 容器中运行任意 JavaScript，并即时安装 npm 依赖。

👉 查看官方网站

📦 在 Docker Hub 上获取

功能

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

注意：容器运行时会受到受控的 CPU 和内存限制。

探索有趣的用例

如果你想了解如何以有趣而强大的方式使用此库，可以查看网站上的用例部分 其中包含精心整理的提示词、示例和创意实验，你可以使用 Node.js Sandbox MCP 服务进行尝试。

⚠️ 前提条件

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

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

推荐镜像示例：

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

入门

要开始使用此 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
        "mcp/node-code-sandbox"
      ]
    }
  }
}

或使用 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

在容器中运行服务（如有需要，挂载 Docker socket），并通过环境变量传入所需的主机输出目录：

# Build locally if necessary
# docker build -t mcp/node-code-sandbox .

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" \
  mcp/node-code-sandbox stdio

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

临时使用——无持久化存储

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  alfonsograziano/node-code-sandbox-mcp stdio

与 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", // optional
                "-e", "FILES_DIR=$HOME/Desktop/sandbox-output",  // optional
                "-e", "SANDBOX_MEMORY_LIMIT=512m",
                "-e", "SANDBOX_CPU_LIMIT=1",
                "mcp/node-code-sandbox"
              ]
        }
    }
}

API

工具

run_js_ephemeral

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

输入：

• image（字符串，可选）：要使用的 Docker 镜像（默认：node:lts-slim）。
• code（字符串，必填）：要执行的 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 文件。

sandbox_initialize

启动一个全新的沙盒容器。

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

sandbox_exec

在运行中的沙盒内执行 shell 命令。

• 输入：
  • container_id（字符串）：来自 sandbox_initialize 的 ID
  • commands（字符串[]）：要执行的 shell 命令数组
• 输出：各条命令的 stdout 合并结果

run_js

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

• 输入：

  • container_id（字符串）：来自 sandbox_initialize 的 ID
  • 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 或后台执行通知

sandbox_stop

终止并移除沙盒容器。

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

search_npm_packages

根据搜索词搜索 npm 包，并获取其名称、描述和 README 片段。

• 输入：

  • searchTerm（string，必填）：用于搜索 npm 包的词语。应包含所有相关上下文。使用加号（+）组合相关词语（例如，用 "react+components" 搜索 React 组件库）。
  • qualifiers（object，可选）：用于筛选搜索结果的可选限定条件：
    • author（string，可选）：按包作者名称筛选
    • maintainer（string，可选）：按包维护者名称筛选
    • scope（string，可选）：按 npm 作用域筛选（例如，Vue.js 包的 "@vue"）
    • keywords（string，可选）：按包关键词筛选
    • not（string，可选）：排除符合此条件的包（例如，"insecure"）
    • is（string，可选）：仅包含符合此条件的包（例如，"unstable"）
    • boostExact（string，可选）：提高搜索结果中与此词语完全匹配的条目的排名

• 行为：

  1. 使用提供的搜索词和限定条件搜索 npm 注册表
  2. 最多返回 5 个包，并按受欢迎程度排序
  3. 为每个包提供名称、描述和 README 片段（前 500 个字符）

• 输出：包含包详情的 JSON 数组，包括名称、描述和 README 片段

使用技巧

• 基于会话的工具（sandbox_initialize ➔ run_js ➔ sandbox_stop）适用于以下情况：
  • 保持沙盒容器长时间运行。
  • 在同一环境中运行多个命令或脚本。
  • 逐步安装并重复使用依赖项。
• 单次执行（run_js_ephemeral）适用于以下情况：
  • 快速试验或运行简单脚本。
  • 无需保留状态或缓存依赖项。
  • 无需手动清理即可进行干净、原子化的运行。
• 分离模式适用于以下情况：
  • 按需启动服务器或长时间运行的服务
  • 从正在运行的容器中公开并测试端点

请选择最适合你使用场景的工作流！

构建

编译并打包：

npm install
npm run build

许可证

MIT 许可证

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

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

本软件按“原样”提供，不提供任何明示或默示的保证，包括但不限于对适销性、特定用途适用性和不侵权的默示保证。在任何情况下，作者或版权所有者均不对因本软件或本软件的使用或其他处理而引起的任何索赔、损害或其他责任承担责任，无论是在合同诉讼、侵权诉讼还是其他诉讼中。