🐢🚀 Node.js Sandbox MCP Server

🐢🚀 Node.js Sandbox MCP サーバー

オンデマンドで npm の依存関係をインストールし、使い捨ての Docker コンテナー内で任意の JavaScript を実行する、Model Context Protocol（MCP）を実装した Node.js サーバーです。

👉 公式ウェブサイトを見る

📦 Docker Hub で利用できます

機能

• 分離された Node.js サンドボックスコンテナーを起動して管理します
• コンテナー内で任意のシェルコマンドを実行します
• ジョブごとに指定した npm の依存関係をインストールします
• ES モジュールの JavaScript スニペットを実行し、標準出力を取得します
• コンテナーを適切に終了します
• デタッチモード： スクリプトの実行後もコンテナーを起動したままにします（長時間稼働するサーバーなど）

注：コンテナーは 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.
  

  これにより、マウントしたディレクトリ（デスクトップなど）に「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 ソケットをマウント）、ホスト上の出力先ディレクトリを環境変数として渡します：

# 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. キャプチャした標準出力を返します。
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

実行中のサンドボックス内でシェルコマンドを実行します。

• 入力：
  • container_id（文字列）：sandbox_initialize から取得した ID
  • commands（文字列[]）：実行するシェルコマンドの配列
• 出力：各コマンドの標準出力を結合したもの

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
• 出力：確認メッセージ

search_npm_packages

検索語を使用して npm パッケージを検索し、名前、説明、README の抜粋を取得します。

• 入力：

  • searchTerm (string, required)：npm パッケージを検索する語句です。関連する情報をすべて含めてください。関連する語句はプラス記号（+）で組み合わせます（例：React コンポーネントライブラリの場合は "react+components"）。
  • qualifiers (object, optional)：検索結果を絞り込むための任意の条件です。
    • author (string, optional)：パッケージの作成者名で絞り込みます
    • maintainer (string, optional)：パッケージのメンテナー名で絞り込みます
    • scope (string, optional)：npm スコープで絞り込みます（例：Vue.js パッケージの場合は "@vue"）
    • keywords (string, optional)：パッケージのキーワードで絞り込みます
    • not (string, optional)：この条件に一致するパッケージを除外します（例："insecure"）
    • is (string, optional)：この条件に一致するパッケージのみを含めます（例："unstable"）
    • boostExact (string, optional)：検索結果で、この語句との完全一致を優先します

• 動作：

  1. 指定された検索語と条件を使用して npm レジストリを検索します
  2. 人気順に最大 5 個のパッケージを返します
  3. 各パッケージについて、名前、説明、README の抜粋（先頭 500 文字）を提供します

• 出力：パッケージの詳細（名前、説明、README の抜粋）を含む JSON 配列

使用上のヒント

• セッションベースのツール（sandbox_initialize ➔ run_js ➔ sandbox_stop）は、次のような場合に適しています。
  • サンドボックスコンテナーを長時間起動したままにする場合。
  • 同じ環境で複数のコマンドやスクリプトを実行する場合。
  • 依存関係を段階的にインストールして再利用する場合。
• 単発実行のrun_js_ephemeralは、次のような場合に最適です。
  • 手早い実験や簡単なスクリプトを実行する場合。
  • 状態や依存関係のキャッシュを保持する必要がない場合。
  • 手動で終了処理を行うことなく、クリーンで独立した実行を行う場合。
• デタッチモードは、次のような場合に便利です。
  • サーバーや長時間稼働するサービスをその場で起動する場合。
  • 実行中のコンテナーからエンドポイントを公開してテストする場合。

用途に最適なワークフローを選択してください。

ビルド

コンパイルしてバンドルします。

npm install
npm run build

ライセンス

MIT ライセンス

本ソフトウェアおよび関連するドキュメントファイル（以下「ソフトウェア」）の複製を取得するすべての者に対し、使用、複製、変更、結合、公開、配布、サブライセンス、および／または販売する権利を含め、ソフトウェアを制限なく取り扱うことを無償で許可します。また、ソフトウェアを提供された者に同様の権利を許可することを認めます。ただし、以下の条件に従うものとします。

上記の著作権表示および本許諾表示は、ソフトウェアのすべての複製または実質的な部分に含めるものとします。

本ソフトウェアは「現状のまま」提供され、商品性、特定目的への適合性、および権利非侵害に関する保証を含め、明示または黙示を問わず、いかなる保証もありません。著作者または著作権者は、本ソフトウェアまたはその使用に起因または関連して生じるいかなる請求、損害、その他の責任についても、契約、不法行為、その他いかなる根拠によるものであっても責任を負いません。