🐢🚀 Node.js 沙盒 MCP 服务器

Node.js 服务器实现了模型上下文协议 (MCP)，用于在临时 Docker 容器中运行任意 JavaScript，并动态安装 npm 依赖项。

👁 网站预览

👉查看官方网站

特征

• 启动和管理隔离的 Node.js 沙盒容器

• 在容器内执行任意shell命令

• 为每个作业安装指定的 npm 依赖项

• 运行 ES 模块 JavaScript 代码片段并捕获标准输出

• 彻底拆除容器

• **分离模式：**脚本执行后保持容器活动（例如，对于长时间运行的服务器）

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

Related MCP server: MCP-REPL

探索酷炫用例

如果您想了解使用此库的酷炫而强大的方法，请查看网站上的用例部分，它包含一个精选的提示、示例和创造性实验列表，您可以使用 Node.js Sandbox MCP 服务器进行尝试。

⚠️ 先决条件

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

**提示：**预先拉取您需要的所有 Docker 镜像，以避免首次执行期间出现延迟。

推荐图片示例：

• 节点：lts-slim

• mcr.microsoft.com/playwright:v1.52.0-noble

• alfonsograziano/node-chartjs-canvas:最新

入门

为了开始使用这个 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.

  这应该在您安装的目录（例如桌面）中创建一个名为“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

在容器中运行服务器（如果需要，安装 Docker 套接字），并将所需的主机输出目录作为环境变量传递：

# 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 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 （ { name, version }数组，可选）：要安装的 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('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 （ string[] ）：要执行的shell命令数组

• 输出：每个命令的组合标准输出

运行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. 清理工作区，除非以分离模式运行

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

sandbox_stop

终止并删除沙盒容器。

• 输入：

  • container_id （字符串）：来自sandbox_initialize ID

• 输出：确认信息

使用技巧

• 当您想要执行以下操作时**，基于会话的工具**（ sandbox_initialize ➔ run_js ➔ sandbox_stop ）是理想的选择：

  • 保持长期沙盒容器处于打开状态。

  • 在同一环境中运行多个命令或脚本。

  • 逐步安装并重用依赖项。

• 使用run_js_ephemeral进行一次性执行非常适合：

  • 快速实验或简单脚本。

  • 您不需要维护状态或缓存依赖的情况。

  • 干净、原子运行，无需担心手动拆卸。

• 当您想要执行以下操作时，分离模式很有用：

  • 即时启动服务器或长期服务

  • 从正在运行的容器中公开和测试端点

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

建造

编译并捆绑：

npm install
npm run build

执照

MIT 许可证

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

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

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

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers