boxes-mcp

ローカル Model Context Protocol (MCP) サーバーで、互換性のあるエージェントや開発者向けハーネスが libvirt/virsh を通じて GNOME Boxes の仮想マシンを管理できるようにします。安全で元に戻せる VM 操作、スナップショット、スクリーンショット、制限付きのキーボードおよびマウス入力、ケーパビリティ・ゲート付きの SPICE 機能を提供します。

このプロジェクトは、GNOME Boxes が利用する Linux の libvirt/QEMU スタックを意図的にターゲットにしています。VMware と VirtualBox は現在サポートしていません。これらの仮想化環境のディスプレイ、入力、ゲストエージェント、クリップボード、ドラッグ&ドロップの各 API は、信頼とケーパビリティの契約が異なるため、libvirt の実装から推定して対応するのではなく、それぞれ独立した、エビデンスに基づくプロバイダーとして追加されるべきです。

目次

• インストール

• 設定

• 利用可能なツール

• 使用例

• 開発

• トラブルシューティング

• セキュリティに関する考慮事項

Related MCP server: kwin-mcp

機能

• 🖥️ VM ライフサイクル管理 - VM の起動、停止、再起動、一時停止、再開

• 📸 スナップショット操作 - VM スナップショットの作成、一覧、復元、削除

• 🔍 VM の検出 - 詳細情報とともにすべての VM を一覧表示し、検査

• 🔒 安全な操作 - デフォルトでストレージを保持し、破壊的な動作なし

• 🎯 GNOME Boxes 互換 - GNOME Boxes の VM とシームレスに連携

• 🖱️ 制御された操作 - スクリーンショット、許可リスト方式のキーボード、型付きマウスツール

• 🔌 ケーパビリティ・ゲート付き SPICE - SPICE 入力、クリップボード、転送のためのオプションのネイティブヘルパープロトコル

• ⚡ 高速・軽量 - 最小限のオーバーヘッドで、virsh を直接統合

インストール

ホストの前提条件

• Ubuntu 22.04/24.04 (または互換性のある Linux ディストリビューション)

• libvirt-daemon-system、qemu-kvm がインストールされていること

• Node.js 18 以上と npm

• ユーザーが libvirt および kvm グループに所属していること

• ライフサイクル、スクリーンショット、キーボード、QMP フォールバック操作のために、virsh が PATH 上で利用可能なこと

SPICE バックエンドのツールには、さらに SPICE ディスプレイ、ゲストの virtio-serial エージェントチャネル、実行中の spice-vdagent (または同等のゲストエージェント) が必要です。クリップボードのサポートは、そのエージェントが 제공するゲストデスクトップ統合にも依存します。標準の spice-vdagent セッションコンポーネントは X11 指向です。Wayland/Hyprland ゲストでは、パッケージとサービスが実行されていても、クリップボードに対して capability-missing を報告することがあります。オプショナルのネイティブヘルパーを少なくともビルドするのは、ホストが spice-client-glib、json-glib、および GLib 開発ファイルを提供する場合のみにしてください。graphics XML に listen type='none' を使用している libvirt ドメインでは、ヘルパーは libvirt のローカルグラフィック FD API を使用します。remote-viewer、virt-viewer、パブリック SPICE URI は不要です。

npm run build:spice-helper
BOXES_SPICE_HELPER="$PWD/native/boxes-spice-helper" npm test

ヘルパーは自動的にインストールまたは選択されません。BOXES_SPICE_HELPER には、このリポジトリからビルドしたレビュー済み実行ファイルだけを設定し、バージョン付きプロトコルを実装する別のプロセスにも同じ方針を適用してください。

# Install dependencies
sudo apt install -y libvirt-daemon-system qemu-kvm virt-manager

# Add your user to required groups
sudo usermod -aG libvirt,kvm "$USER"
newgrp libvirt

npm からのインストール

npm パッケージには、ローカル MCP ホスト向けのガイド付きインストーラーが含まれています。Node.js サーバーのみをインストールします。libvirt、virsh、QEMU、およびオプションの SPICE 開発ライブラリは、引き続きホスト側の前提条件です。

# Detect installed MCP hosts and configure them
npx -y boxes-mcp@0.1.0 setup

# Or install the command globally
npm install --global boxes-mcp@0.1.0
boxes-mcp setup

ファイルを書き込まずに設定をプレビュー:

npx -y boxes-mcp@0.1.0 setup --dry-run

ホストが PATH 上で検出されない場合は、明示的に設定:

npx -y boxes-mcp@0.1.0 setup --client codex
npx -y boxes-mcp@0.1.0 setup --client claude
npx -y boxes-mcp@0.1.0 setup --client openclaw

インストーラーは Codex、Claude Code、OpenClaw、Antigravity、Gemini CLI、OpenCode、Cursor、Windsurf、VS Code、Pi、Cline、Zed、Goose を検出するか、または明示的に設定できます。別の stdio 対応エージェント用にポータブルな JSON 設定を出力するには、--client generic を使用してください:

npx -y boxes-mcp@0.1.0 setup --client generic

セットアップコマンドは選択された MCP エントリのみを書き込み、既存の設定を変更する前に一度だけ .boxes-mcp.bak バックアップを作成し、原子的置換を使用します。オペレーティングシステムのパッケージをインストールしたり、VM 定義を変更したりすることはありません。セットアップ後、設定したエージェントまたはハーネスを再起動してください。boxes-mcp doctor を実行して、Node.js と virsh、検出されたホストを検査します。

セットアップ中に、オプションのホスト設定を永続化できます:

npx -y boxes-mcp@0.1.0 setup \
  --libvirt-uri qemu:///session \
  --input-backend auto \
  --spice-helper /absolute/path/to/native/boxes-spice-helper \
  --transfer-root /absolute/path/to/approved/files

ネイティブ SPICE ヘルパーはユニバーサルバイナリとして配布されていません。ホストの SPICE/libvirt 開発パッケージをインストールした後、互換性のある Linux ホスト上でビルドし、レビュー済みの絶対パスを --spice-helper または BOXES_SPICE_HELPER で渡してください。

ソースからのインストール

# Clone the repository for unreleased changes or development
git clone https://github.com/EF-Code/boxes-mcp.git
cd boxes-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Configure a local checkout with the same guided installer
npm run setup:guided -- --client codex

設定(Configuration)

手動インストールの場合は、Claude Code の設定ファイル (~/.claude.json) にサーバーを追加します:

{
  "mcpServers": {
    "boxes": {
      "command": "node",
      "args": ["/absolute/path/to/boxes-mcp/dist/src/index.js"],
      "env": {
        "LIBVIRT_URI": "qemu:///system",
        "BOXES_INPUT_BACKEND": "auto"
      }
    }
  }
}

利用可能なツール

VM 管理

スナップショット管理

表示と操作

操作ツールは、シェルフラグメント、生の QMP JSON、任意の virsh フラグ、ゲストコマンド、任意の転送先を受け付けることはありません。新しい操作には、実行中のドメインが必要で、バックエンドが利用できない場合は、安定した capability/error コードを返します。

オプション環境変数

BOXES_TRANSFER_ROOT は、推測ではなく意図的に必須としています。パスは正規化され、シンボリックリンクからの脱出、ディレクトリ、特殊ファイルは拒否されます。

boxes.capabilities は観測された状態を報告します。設定だけでは接続済みとはみなされません。外部からの状態プローブが必要な場合は、probeQmp: true や probeSpice: true を使用してください。SPICE のクリップボードと転送には、接続されたゲストエージェントが必要です。boxes.drag_drop は、外部ビューアハーネスがアプリケーションレベルのエビデンスを提供しない限り、 applicationAccepted: \"unknown\" を報告します。

キーボード入力は、固定された Linux virsh コードセットを使用します。公開キー名は大文字小文字を区別せず、大文字に正規化されますが、各キーは 1 回のコード (キーを同時押しするコード) につき 1 回だけ出現できます。許可リストは次のとおりです: ALT、BACKSPACE、CAPSLOCK、CTRL、DELETE、DIGIT_0 から DIGIT_9、DOWN、END、ENTER、ESC、ESCAPE、F1 から F12、HOME、INSERT、LEFT、META、NUMLOCK、PAGEDOWN、PAGEUP、PAUSE、PRINT、RIGHT、 SHIFT、SPACE、SUPER、TAB、UP、A から Z。ゲストのキーボードレイアウトにより、生成される文字が決まります。つまり、キー許可リストはレイアウトに依存せずに特定のテキストを保証するわけではありません。

使用例

Claude Code で使用

User: "List all my VMs"
Claude: [Uses boxes.list tool]

User: "Start ubuntu-24.04"
Claude: [Uses boxes.start with nameOrUuid="ubuntu-24.04"]

User: "Create a snapshot called 'before-update' for my fedora VM"
Claude: [Uses boxes.snapshots.create]

直接使用

# Run the MCP server
LIBVIRT_URI=qemu:///system node dist/src/index.js

開発

プロジェクト構成

boxes-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── tools.ts          # Side-effect-free tool registry and handler boundary
│   ├── libvirt.ts        # virsh operations & parsers
│   ├── virsh.ts          # Shared executable and libvirt URI arguments
│   ├── exec.ts           # Safe command execution
│   ├── screenshot.ts     # Controlled libvirt screenshot capture
│   ├── keyboard.ts       # Allowlisted virsh send-key adapter
│   ├── mouse.ts/qmp.ts   # Typed mouse actions and QMP fallback
│   ├── spice.ts          # Versioned companion-helper protocol client
│   ├── clipboard.ts      # Explicit SPICE clipboard orchestration
│   ├── transfer.ts       # Confined host-file validation
│   ├── drag-drop.ts      # Experimental transfer/input coordination
│   ├── *.test.ts         # Unit tests
├── systemd/
│   └── boxes-mcp.service # Systemd user service
├── dist/                 # Compiled JavaScript
├── coverage/             # Test coverage reports
├── package.json
├── tsconfig.json
└── vitest.config.ts

テスト

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

ローカルテストカバレッジ: 現在の checkout では、95 のテストがパスし、9 のゲート付きライブテストはデフォルトでスキップされます。デフォルトのスイートは、libvirt アクセスなしでも安全に実行できます。

• exec.ts: ステートメント 100%

• libvirt.ts: ステートメント 81.3%、ブランチ 92.85%

• 操作検証、コマンド構築、QMP 応答マッピング、アーティファクトクリーンアップ、ヘルパーフレーミング、機能発見、パス制限テスト

明示的なローカルネイティブヘルパーのプロセスチェックを実行するには:

npm run test:spice-helper

3 つの安全変数をすべて設定した場合のみ、廃棄可能 VM スイートを実行します:

BOXES_INTEGRATION=1 \
BOXES_TEST_VM=an-explicit-disposable-domain \
BOXES_TEST_VM_DISPOSABLE=1 \
npm run test:integration

ライブスイートは、一覧表示された VM を選択したり、VM 定義を変更したり、ゲストサービスを停止したりすることはありません。ゲストエージェント切断のカバレッジでは、明示的に廃棄できるゲスト内で spice-vdagent を手動で切断し、BOXES_TEST_AGENT_DISCONNECTED=1 を追加する必要があります。廃棄可能なゲスト以外では、絶対にこの操作を行わないでください。

デフォルトのスイートはモック／ローカルであり、QMP、SPICE、クリップボード、またはドラッグ＆ドロップが実際のVMに対して動作することを証明するものではありません。ライブテストはオプトイン方式とし、名前を明示した使い捨てVMを対象としなければなりません。操作ツールが任意の先頭リストのドメインを選択することはありません。

ビルド

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

任意のsystemdユーザーサービス

チェックイン済みのユニットはソースチェックアウトを想定したものです。サーバーがエージェントのMCP設定によって起動される場合や、npmでグローバルインストールされる場合には不要です。チェックアウト後の自動起動用にユーザーサービスとしてインストールしてください：

BOXES_MCP_DIR="$(pwd)"
NODE_BIN="$(command -v node)"
mkdir -p ~/.config/systemd/user
cp systemd/boxes-mcp.service ~/.config/systemd/user/
sed -i \
  -e "s|/usr/bin/node|$NODE_BIN|g" \
  -e "s|%h/projects/boxes-mcp|$BOXES_MCP_DIR|g" \
  ~/.config/systemd/user/boxes-mcp.service
systemctl --user daemon-reload
systemctl --user enable --now boxes-mcp
journalctl --user -fu boxes-mcp

セキュリティに関する考慮事項

• ✅ サンドボックス実行：Node.jsのexecFileをタイムアウトおよびバッファ制限付きで使用

• ✅ 任意コマンドなし：事前定義されたvirsh操作のみ許可

• ✅ 型付き入力境界：QMPコマンドとSPICE操作は検証済み引数を備えた内部enum

• ✅ ペイロード制限：キー数、ホールド時間、座標、スクロールデルタ、スクリーンショット、クリップボード、転送は上限付き

• ✅ パス制限：ドラッグ＆ドロップのソースは正規化後にBOXES_TRANSFER_ROOT配下に存在する必要があります

• ✅ ストレージ保護：VMストレージはデフォルトでは削除されません

• ✅ LIBVIRT_URI分離：環境変数で指定されたlibvirt接続を尊重します

• ⚠️ 権限要件：ユーザーはlibvirtグループのメンバーシップが必要です

• ⚠️ ネットワーク露出：追加のセキュリティなしでのリモートアクセスは想定されていません

• ⚠️ 操作面の拡大：スクリーンショットとゲストのクリップボードデータは信頼できないため、MCPサーバーはローカルのstdio上に維持してください

• ⚠️ SPICEヘルパーの信頼性：ヘルパー実行ファイルは明示的なホスト依存関係であり、認証情報、クリップボード内容、ファイル内容をログに記録してはなりません

SPICEヘルパープロトコル

TypeScriptサーバーは1つの永続的なヘルパーチャイルドを起動し、stdinを介して改行区切りのバージョン1 JSONリクエストを送信し、リクエストIDでレスポンスを対応付けます。ヘルパーは明示的な実行ファイルパスと呼び出し元が制御できない引数で呼び出されます。リクエストエンベロープは次のような形式です：

{
  "version": 1,
  "id": "request-123",
  "operation": "clipboard.read",
  "domain": "guest-name",
  "display": { "uri": "spice://127.0.0.1:5900" },
  "arguments": { "selection": "clipboard", "maxBytes": 1048576 }
}

サポートされる操作名は内部定義です（status、mouse、clipboard.read、clipboard.write、file.transfer、drag-drop）。ヘルパーエラーはSPICE_AGENT_DISCONNECTED、SPICE_CAPABILITY_MISSING、SPICE_UNAVAILABLEなどの安定したMCPエラーにマッピングされます。ペイロード、行、保留中リクエスト、転送サイズ、クリップボードバイト、操作時間はすべて上限付きです。進行イベントがリクエストを完了させることはありません。ヘルパーはクリップボード内容、ファイル内容、SPICEチケット、認証情報をログに記録しません。

機能マトリクス

クリップボードサポートはゲストのデスクトップ統合に依存します。現在のSPICEゲストエージェントはX11指向であるため、Hyprland/OmarchyなどのWaylandゲストでは、spice-vdagentがインストールされ実行中であってもSPICE_CAPABILITY_MISSINGが報告されることがあります。マウスとファイル転送は独立して動作できます。

トラブルシューティング

VMが一覧に表示されない

# Check libvirt URI
virsh -c qemu:///system list --all
virsh -c qemu:///session list --all

# Verify permissions
groups  # Should include 'libvirt' and 'kvm'

権限拒否

# Re-add to groups and re-login
sudo usermod -aG libvirt,kvm "$USER"
# Then logout/login or:
newgrp libvirt

BoxesにVMが表示されない

virt-managerを開き、VMが使用している接続を確認してください：

• システム接続：qemu:///system

• ユーザーセッション：qemu:///session

LIBVIRT_URI環境変数をそれに応じて設定してください。

SPICE機能エラー

virsh domdisplayがNo graphical display foundを報告し、ドメインXMLに<graphics type='spice'><listen type='none'/></graphics>が含まれている場合、それは意図的なlibvirt設定であり、パブリックリスナーは存在しません。ビューアURIを取得するためにポートを独自に設定したりVM定義を変更したりしないでください。ネイティブヘルパーが設定されている場合、boxes-mcpは内部のspice+libvirt-fd://localトランスポートを使用し、各SPICEチャネルについてlibvirtにグラフィックスFDを要求します。ヘルパーはMCPプロセスと同じlibvirt接続を使用する必要があります：

LIBVIRT_URI=qemu:///session npm run build:spice-helper
BOXES_SPICE_HELPER="$PWD/native/boxes-spice-helper" \
LIBVIRT_URI=qemu:///session node dist/src/index.js

ドメインが実行中であり、ヘルパーがlibvirtおよびspice-client-glibにリンクされ、ゲストがvirtio SPICEエージェントチャネルを公開している必要があります。接続されたエージェントでもクリップボード機能が欠如している場合があります。その場合は、XMLだけから推測するのではなく、boxes.capabilitiesをprobeSpice: trueで検査してください。

boxes.capabilitiesをprobeSpice: trueで使用し、返された状態を確認してください：

• configured：レビュー済みのヘルパーとSPICEエンドポイントが設定されているが、接続の証明はまだ要求されていない；

• connecting：ヘルパーが不完全なチャネルセットを観測した；

• connected：必要なチャネルがすべて接続されている；

• agent-disconnected：ゲストエージェントが接続されていない；

• capability-missing：バックエンド、チャネル、ヘルパー、またはゲスト機能が存在しない。

たとえば、ファイル転送をサポートするがクリップボードをアナウンスしない接続済みゲストエージェントは、capability-missingであり、agent-disconnectedではありません。クリップボードを有効にするには、ゲストにそのディストリビューションのspice-vdagentサービスがインストールされ、デスクトップセッションで実行され、virtio SPICEエージェントチャネル経由で接続されている必要があります。Wayland/Hyprlandデスクトップでは、ディストリビューションのエージェントが実際にそのコンポジタをサポートしていることを確認してください。アクティブなサービスだけでは証明になりません。実際のOmarchyゲストでは、spice-vdagent 0.23.0-1とアクティブなユーザーサービスがあったものの、xrandr output ID NOT FOUNDをログに記録し、org.gnome.Mutter.DisplayConfigのオーナーがいなかったため、boxes-mcpは正しくSPICE_CAPABILITY_MISSINGを返しました。現在のアップストリームエージェントにはX11ゲストセッションを使用するか、別途検証済みのWaylandクリップボードブリッジを提供してください。サーバーはゲストパッケージをインストールしたり、ゲストサービスを自動起動したりしません。

永続的なSPICEクライアントはアボートシグナルも受け付けます。キャンセルにより現在のヘルパープロセスが終了し、すべての保留中操作が決定的に失敗し、次のリクエストでクリーンなセッションを作成できます。これはOPERATION_CANCELLEDとして報告されます。

ホストの依存関係とヘルパーを、VMに入力を送信せずに直接確認してください：

pkg-config --modversion spice-client-glib-2.0 json-glib-1.0 gio-unix-2.0
npm run build:spice-helper

ヘルパーのローカルプロトコルテストは意図的に127.0.0.1:1に接続し、型付きの利用不可／切断結果を期待します。これはライブSPICEの証明にはなりません。

ロードマップ

• virt-install統合によるVM作成

• ネットワーク管理（virsh net-list、ポートフォワーディング）

• ストレージプール情報（virsh vol-list）

• OVA/QCOW2からのVMインポート

• リモートlibvirt接続サポート

• パフォーマンスメトリクスとモニタリング

貢献

貢献を歓迎します！ガイドラインについてはCONTRIBUTING.mdをお読みください。

1. リポジトリをフォークする

2. フィーチャーブランチを作成する（git checkout -b feature/amazing-feature）

3. テストを実行する（npm test）

4. 変更をコミットする（git commit -m 'Add amazing feature'）

5. ブランチにプッシュする（git push origin feature/amazing-feature）

6. プルリクエストを開く

ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細はLICENSEファイルを参照してください。

謝辞

• Claude Code向けに構築

• Model Context Protocol SDKを使用

• libvirt仮想化APIと統合

サポート

• 問題報告：GitHub Issues

• ディスカッション：GitHub Discussions

• ドキュメント：プロジェクトWiki

Claude Codeコミュニティのために❤️を込めて作られました