Mcp Virtualbox

mcp-virtualbox

AI が仮想マシンを認識し、クリックや入力を行い、完全に操作できるようにします。OS のベアメタルインストールから日常的な使用まで、人間の手を借りずに実行できます。

お知らせ：このプロジェクトの後継は terrarium です。

このリポジトリは、「AI に実際の VM を操作させる」というアイデアから始まりました。次のバージョンは、イミュータブルなゴールデンイメージ、サブ秒でのフォーク、数秒でのクリーンな状態への復元、MCP サーバーと並行して使えるフル機能の CLI など、十分に異なるものへと成長したため、ここでの新しいリリースではなく、独立したプロジェクトになりました。

より高度な仕組みをお探しですか？terrarium をご覧ください。 mcp-virtualbox は、すでに提供しているシンプルでクロスプラットフォーム対応の VirtualBox MCP サーバーをお求めの方のために、引き続きメンテナンスされ、利用可能な状態に保たれます。

TL;DR

Claude Code（簡単なインストール）

/plugin marketplace add chryaner/mcp-virtualbox
/plugin install mcp-virtualbox@mcp-virtualbox

Claude Code / Claude Desktop（手動）

.mcp.json または claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "mcp-virtualbox": {
      "command": "npx",
      "args": ["-y", "mcp-virtualbox"]
    }
  }
}

VirtualBox 7.x と Node.js 18+ が必要です。

OS インストーラー ISO はご自身で用意してください。場所とインストールする OS を AI に伝えるだけで使えます。

---

概要

VirtualBox をラップし、AI アシスタントが 2 つのモードを使って VM の作成、インストール、操作を行えるようにする MCP サーバーです。30 個のツールを提供します。

1. ビジョンループ — スクリーンショットの撮影、画面の読み取り、キーボード／マウス操作を行います。あらゆる OS、インストーラー、GUI で動作します。
2. テキストモード — SSH、WinRM、または Guest Additions を使って、コマンドを高速に実行します。

仕組み

vm_create("WindowsXP")          -> VM with correct settings (IDE, 512MB RAM)
vm_attach_media(iso)             -> Mount installer ISO
vm_install_guide("xp")           -> Step-by-step guide with gotchas
vm_screenshot()                  -> AI sees "Welcome to Setup"
vm_keyboard_scancode("enter")    -> AI presses Enter
  ... repeat until installed ...
vm_guest_exec("cmd.exe", ["/c", "dir"])  -> Text-based control

ツール

6 つのカテゴリにわたる 30 個のツール：

カテゴリ	ツール
ライフサイクル（15）	vm_list vm_info vm_create vm_start vm_stop vm_delete vm_pause vm_resume vm_reset vm_attach_media vm_snapshot vm_modify vm_list_ostypes vm_shared_folder_add vm_shared_folder_remove
ディスプレイ（2）	vm_screenshot vm_screen_info
入力（3）	vm_keyboard_scancode vm_keyboard_type vm_mouse_click
ゲスト制御（3）	vm_guest_exec vm_guest_copy_to vm_guest_copy_from
ネットワーク（6）	vm_exec_ssh vm_exec_winrm vm_get_guest_ip vm_wait_for_guest_additions vm_wait_for_network vm_add_nat_port_forward
ナレッジ（1）	vm_install_guide

テスト状況

	Windows XP	Windows 7/10/11	Ubuntu/Linux
OS インストール（ビジョンループ）	x	-	-
Guest Additions	x	-	-
ゲスト実行	x	-	-
SSH	-	-	-
WinRM	-	-	-
スクリーンショット＋キーボード	x	-	-
マウスクリック	x	-	-

ホストプラットフォーム： Windows x64（テスト済み）、Linux/macOS（動作する見込みです）。

x = テスト済み、- = 動作する見込みですが未検証

環境変数

変数	デフォルト
VBOXMANAGE_PATH	自動検出
VBOXMANAGE_DRY_RUN	false
VBOXMANAGE_DEBUG	false

ソースから実行

git clone https://github.com/chryaner/mcp-virtualbox.git
cd mcp-virtualbox
npm install && npm run build

Python 3 の vboxapi モジュールは任意です（vm_mouse_click にのみ必要です）。

ライセンス

MIT