desktop-hypervisor-mcp

デスクトップハイパーバイザー MCP

デスクトップハイパーバイザー向けの、プロバイダーに依存しない単一の MCP サーバーです。対応するのは VirtualBox、 VMware Fusion、VMware Workstation です。9 個のツールで約 1,800 コンテキストトークンを使用し、 先行する 2 つのサーバーが約 5,600 トークンで提供していた機能をすべてカバーします。

virtualbox-mcp-server を後継するプロジェクトです（その履歴は predecessor-virtualbox ブランチに保存されています）。また、リリースされなかった vmware-fusion-mcp-server の機能も 統合し、機能ベースの単一のインターフェースにまとめています。

バージョンに関する注意： このサーバーの安定版は v2.0.0 から始まります。v1.x 系列（および、 引き続き固定バージョンを指定するユーザー向けに残されている v1.0.0 リリース）は、VirtualBox 専用の先行プロジェクトのものです。 0.x タグは、このサーバーの安定版リリース前のバージョンです。v2.0.0 は内容としては v0.4.3 と同一で、 安定版系列としてバージョンを付け直したものです。

設計

• 最小公倍数ではなく、機能ベースです。 プロバイダーは、実際に実行できる操作を通知します（provider action=list）。 ゲストでのコマンド実行、OVA のインポート／エクスポート、リンククローン、起動前の guestinfo 注入、DHCP リースによる IP 検出、 ISO の作成などが含まれます。未対応の操作は、プロバイダーエラーではなく、不足している機能を示して失敗します。
• 仕組みではなく、目的を表現します。 「クラスターのノードが、ホストから到達できるネットワークを共有できるようにする」 ことはどちらのファミリーでも表現できますが、「ホストオンリーインターフェースを作成する」ことはできません。中立的なツールで 目的を表現し、プロバイダー固有の仕組みには抽象化を介さず、execute_command からアクセスできます。
• アーティファクトはプロバイダーごとに解決されます。 同じイメージ名でも、各ハイパーバイザーが実際にインポートできる アーティファクトが選択されます。たとえば、Talos では vmware-*.ova と virtualbox-*.ova、Vagrant では vmware_desktop と virtualbox のボックス、Microsoft の開発用 VM ではハイパーバイザーごとの VM が選択されます。 これらは（イメージ、プロバイダーファミリー、ホストのアーキテクチャ）をキーとして解決されます。

ツール

ツール	アクション
provider	list — インストール済みハイパーバイザーのステータス、機能、形式を表示し、準備が整っていない場合は対処方法も表示します
artifact	catalog、resolve、fetch（dry_run）— プロバイダーごとに、公式 OS イメージを検証してダウンロードします
vm_lifecycle	create、start、stop、suspend、reset、delete、clone、import、export
vm_info	list、running、show、ip（ゲスト内のツールを使用し、利用できない場合は MAC アドレスに基づいて DHCP リースを検索します。Talos のようなエージェントレスのゲストにも対応します）
vm_config	resources、nested_virt、attach_iso、guestinfo（起動前のキー／値注入、VMware）
snapshot	take、restore、delete、list（ツリー）
guest	exec、script、copy_in、copy_out、screenshot
network	ensure_cluster_network、expose_guest_port、make_iso、repack_iso
execute_command	選択したプロバイダーで、VBoxManage／vmrun の引数を直接実行します

ハイパーバイザーが 1 つインストールされている場合は自動的に選択されます。複数インストールされている場合は、曖昧さを明示し、 推測で選択することはありません。

イメージカタログ

artifact action=catalog では、管理対象のイメージを一覧表示します。Talos（アプライアンスおよびベアメタル用 ISO）、 Ubuntu（クラウドイメージおよび Vagrant）、Debian、Fedora、Rocky、Alma、openSUSE、FreeBSD、Kali、TurnKey、 Windows 開発用 VM に加えて、レジストリ全体にそのままアクセスできる vagrant:org/box に対応しています。 公開元がダイジェストを提供している場合は、ダウンロードを sha256 で検証します（GitHub のリリースアセットは常に対応しています）。 未検証のソースについては、その旨を明示します。Vagrant のボックスは適切なプロバイダー向けに取得され、 インポート可能なマシンファイルへ自動的に展開されます。キャッシュは ~/.hypervisor-images に保存されます （HV_IMAGE_DIR で変更できます）。

前提条件

• VirtualBox（VBoxManage）、および／または VMware Fusion／Workstation（vmrun）。 検出は呼び出しごとに行われるため、セッションの途中でインストールしたハイパーバイザーも認識されます。
• それ以外は不要です。単一の静的 Go バイナリで動作し、Python や Node は必要ありません。

オプション（実行時に検出）：ovftool があると VMware で OVA のインポート／エクスポートが可能になります。 xorriso があると repack_iso が利用できます。

インストール

公式 MCP Registry に io.github.bryanjbelanger/desktop-hypervisor-mcp として公開されています。レジストリ対応クライアントは、この名前を使ってインストールします。レジストリにはまだサーバーごとのページがないため、掲載情報自体が API レコードです。 現在のエントリー。

MCP Bundles に対応するホストでは、 最新リリース から .mcpb をダウンロードして開きます。ゲストの認証情報とイメージキャッシュのディレクトリは、ホストの UI で入力を求められます。1 つのバンドルですべてのプラットフォームに対応します。各（os、arch）用のバイナリが含まれており、起動時に適切なものが選ばれるため、サイズは約 16 MB です。

それ以外の場合は、同じリリースからプラットフォームに対応するバイナリを取得するか、ビルドしてください。

go build -o desktop-hypervisor-mcp .

Claude Code への登録

claude mcp add --scope user hypervisor -- /path/to/desktop-hypervisor-mcp

ゲスト操作の認証情報はサーバーの環境変数から取得され、ツールのパラメーターから取得されることはありません。

claude mcp add --scope user hypervisor \
  --env HV_GUEST_USER=vagrant --env HV_GUEST_PASSWORD=vagrant \
  -- /path/to/desktop-hypervisor-mcp

（VMRUN_GUEST_USER／VMRUN_GUEST_PASSWORD も互換性のために使用できます。）

サーバーは MCP initialize ハンドシェイクで、ホスト上で実際に検出された内容に基づいて生成された使用レシピを提供します。VirtualBox のみを使用するマシンでのセッションでは、VMware のガイダンスにコンテキストを消費しません。

権限

.claude/settings.json でツールごとに許可リストを設定すると、プロンプトの意味が保たれます。読み取り専用ツールは常に許可しても安全です。

{
  "permissions": {
    "allow": [
      "mcp__hypervisor__provider",
      "mcp__hypervisor__vm_info",
      "mcp__hypervisor__artifact",
      "mcp__hypervisor__snapshot"
    ]
  }
}

無人での VM 変更を許容しない限り、変更を伴うツール（vm_lifecycle、execute_command）はプロンプトによる確認を必須にしてください。

バンドルされたスキル

skills/ には、Claude Code 用のワークフロースキルが含まれています。いずれかのハイパーバイザーでこのサーバーのツールを組み合わせて使う手順です。 hv-vm（プロビジョニング）、 hv-network（ネットワーク、ゲストへの接続性、シード ISO）、 hv-snapshot（安全なワークフロー）、 hv-maintenance（インベントリとクリーンアップ）、 hv-transfer（クローン／エクスポート／移動）。 ~/.claude/skills/ にコピー（またはシンボリックリンク）してインストールしてください。これらは、前身の vbox-* スキルに代わるものです。

関連プロジェクト

• talos-mcp-server — Talos／Kubernetes のオーケストレーションを担います。このサーバーをノードのプロビジョニングに利用し、意図的にハイパーバイザーに依存しない設計になっています。