简介

启用在隔离的 Docker 容器中运行任意 JavaScript 代码，并支持即时 npm 依赖安装，同时兼容短暂的一次性执行和持久化的沙箱环境。

简介

启用在隔离的 Docker 容器中运行任意 JavaScript 代码，并支持即时 npm 依赖安装，同时兼容短暂的一次性执行和持久化的沙箱环境。

🐢🚀 Node.js Sandbox MCP 服务器

Node.js 服务器实现了 Model Context Protocol (MCP)，用于在临时 Docker 容器中运行任意 JavaScript，并支持即时安装 npm 依赖。

功能

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

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

探索酷炫用例

如果您想了解如何以酷炫且强大的方式使用此库，请查看 USE_CASES.md 文件！该文件包含了一系列经过精心策划的提示、示例和创意实验，您可以尝试使用 Node.js Sandbox 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 的 QR 码的 JS 脚本，并将其保存为 qrcode.png 提示： 使用 qrcode 包。

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

与 Claude Desktop 一起使用

将以下内容添加到您的 claude_desktop_config.json 中： 您可以按照 官方指南 来安装此 MCP 服务器

json { "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：

json { "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 套接字），并通过环境变量传递您希望的主机输出目录：

shell

如果有必要，本地构建

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 中：

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 (数组, 包含 { name, version }, 可选): 要安装的 NPM 包及其版本 (默认: [])。

行为:

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

提示: 要获取文件，请在脚本执行过程中简单地保存它们。

示例调用:

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

示例保存文件:

javascript 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 命令数组
• 输出: 每个命令的组合标准输出

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 并捕获标准输出，或如果设置了 listenOnPort 则让进程在后台运行
  5. 清理工作区，除非处于分离模式

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

sandbox_stop

终止并移除沙箱容器。

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

使用技巧

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

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

构建

编译和打包：

shell npm install npm run build

许可证

MIT 许可证

特此授予任何人免费获得本软件及其相关文档文件（“软件”）副本的权利，可以不受限制地使用该软件，包括但不限于使用权、复制权、修改权、合并权、发布权、分发权、再许可权以及/或者销售软件副本的权利，并允许向其提供软件的人也这样做，但须遵守以下条件：

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

本软件按“原样”提供，不附带任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人都不对因使用或无法使用本软件而引起的任何索赔、损害或其他责任负责，无论是合同诉讼、侵权行为还是其他原因。

来源

• 来源：github
• 链接：https://github.com/alfonsograziano/node-code-sandbox-mcp