代码沙箱节点_mCP

Name: 代码沙箱节点_mCP
Author: alfonsograziano

作者：alfonsograziano136 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

🐢🚀 Node.js Sandbox MCP Server

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

网站预览

👉 查看官方网站

📦 可在Docker Hub上获取

功能

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

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

探索酷炫用例

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

⚠️ 先决条件

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

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

推荐的镜像：

node:lts-slim
mcr.microsoft.com/playwright:v1.55.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", // 可选
        "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", // 可选
       
        "SANDBOX_CPU_LIMIT": "0.75" // 可选
      }
    }
  }
}

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

Docker

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

# 如果有必要，本地构建
# 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", // 可选
                "-e", "FILES_DIR=$HOME/Desktop/sandbox-output",  // 可选
                "-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 (数组，可选)：NPM包及其版本（默认：[]）。

行为：

创建一个新的容器。
写入您的index.js和最小的package.json。
安装指定的依赖项。
执行脚本。
销毁（移除）容器。
返回捕获的标准输出。
如果您的代码在当前目录中保存了任何文件，这些文件将自动返回。
- 图像（如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', '你好世界！');
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包名 → 版本号
- 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
输出：确认消息

search_npm_packages

通过搜索词搜索npm包，并获取它们的名称、描述和README片段。

输入：
- searchTerm (字符串，必需)：要在npm包中搜索的术语。应包含所有相关上下文。使用加号（+）组合相关术语（例如，“react+components”用于React组件库）。
- qualifiers (对象，可选)：可选限定符以过滤搜索结果：
  - author (字符串，可选)：按包作者名称过滤
  - maintainer (字符串，可选)：按包维护者名称过滤
  - scope (字符串，可选)：按npm范围过滤（例如，“@vue”用于Vue.js包）
  - keywords (字符串，可选)：按包关键字过滤
  - not (字符串，可选)：排除匹配此标准的包（例如，“不安全”）
  - is (字符串，可选)：仅包括匹配此标准的包（例如，“不稳定”）
  - boostExact (字符串，可选)：在搜索结果中提升此术语的确切匹配
行为：
1. 使用提供的搜索词和限定符搜索npm注册表
2. 返回最多5个按受欢迎程度排序的包
3. 对于每个包，提供名称、描述和README片段（前500个字符）
输出：包含包详细信息的JSON数组，包括名称、描述和README片段

使用技巧

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

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

构建

编译和打包：

npm install
npm run build

许可证

MIT许可证

在此授权下，任何人获得该软件及关联文档文件（以下简称“软件”）的副本，均可不受限制地使用、复制、修改、合并、发布、分发、再许可和/或出售该软件的副本，并允许向他们提供软件的人这样做，但须遵守以下条件：

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