boxes-mcp

Ein lokaler Model Context Protocol (MCP)-Server, der kompatiblen Agenten und Entwickler-Harnesses die Verwaltung von GNOME-Boxes-VMs über libvirt/virsh ermöglicht. Er bietet sichere, reversible VM-Operationen, Snapshots, Screenshots, begrenzte Tastatur- und Mauseingaben sowie funktionsgesteuerte SPICE-Funktionen.

Das Projekt zielt bewusst auf den Linux-libvirt/QEMU-Stack von GNOME Boxes ab. VMware und VirtualBox werden derzeit nicht unterstützt; ihre Display-, Eingabe-, Guest-Agent-, Zwischenablage- und Drag/Drop-APIs haben andere Vertrauens- und Fähigkeitsverträge und sollten als separate, evidenzbasierte Anbieter hinzugefügt werden, anstatt aus der libvirt-Implementierung abgeleitet zu werden.

Inhalt

• Installation

• Konfiguration

• Verfügbare Tools

• Anwendungsbeispiele

• Entwicklung

• Fehlerbehebung

• Sicherheitshinweise

Related MCP server: kwin-mcp

Funktionen

• 🖥️ VM-Lebenszyklusverwaltung – VMs starten, stoppen, neu starten, anhalten und fortsetzen

• 📸 Snapshot-Operationen – VM-Snapshots erstellen, auflisten, zurücksetzen und löschen

• 🔍 VM-Erkennung – Alle VMs mit detaillierten Informationen auflisten und inspizieren

• 🔒 Sichere Operationen – Speichererhaltung standardmäßig, keine destruktiven Aktionen

• 🎯 GNOME-Boxes-kompatibel – Funktioniert nahtlos mit GNOME-Boxes-VMs

• 🖱️ Kontrollierte Interaktion – Screenshot, auf die Whitelist gesetzte Tastatur und getippte Maus-Tools

• 🔌 Funktionsgesteuertes SPICE – Optionales natives Helferprotokoll für SPICE-Eingabe, Zwischenablage und Transfer

• ⚡ Schnell & leichtgewichtig – Minimaler Overhead, direkte virsh-Integration

Installation

Voraussetzungen auf dem Host

• Ubuntu 22.04/24.04 (oder kompatible Linux-Distribution)

• libvirt-daemon-system, qemu-kvm installiert

• Node.js 18+ und npm

• Benutzer in den Gruppen libvirt und kvm

• virsh auf dem PATH verfügbar für Lebenszyklus-, Screenshot-, Tastatur- und QMP-Fallback-Operationen

SPICE-gestützte Tools erfordern zusätzlich ein SPICE-Display, einen Gast-virtio-serial-Agentenkanal und einen laufenden spice-vdagent (oder einen gleichwertigen Gast-Agenten). Die Zwischenablage-Unterstützung hängt auch von der Gast-Desktop-Integration ab, die von diesem Agenten bereitgestellt wird. Die Standard-spice-vdagent-Sitzungskomponente ist X11-orientiert; ein Wayland/Hyprland-Gast kann das Paket und den Dienst ausführen und dennoch capability-missing für die Zwischenablage melden. Erstellen Sie den optionalen nativen Helfer nur, wenn der Host spice-client-glib, json-glib und GLib-Entwicklungsdateien bereitstellt. Für libvirt-Domänen, deren Grafik-XML listen type='none' verwendet, nutzt der Helfer die lokale Grafik-FD-API von libvirt; kein remote-viewer, virt-viewer oder öffentlicher SPICE-URI ist erforderlich:

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

Der Helfer wird nicht automatisch installiert oder ausgewählt. Setzen Sie BOXES_SPICE_HELPER nur auf die geprüfte ausführbare Datei, die aus diesem Repository erstellt wurde, oder auf einen anderen Prozess, der das versionierte Protokoll unten implementiert.

# 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

Installation über npm

Das npm-Paket enthält einen geführten Installer für lokale MCP-Hosts. Es installiert nur den Node-Server; libvirt, virsh, QEMU und optionale SPICE-Entwicklungsbibliotheken bleiben Voraussetzungen auf dem Host.

# 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

Vorschau der Konfiguration ohne Dateien zu schreiben:

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

Konfigurieren Sie einen Host explizit, wenn er nicht über PATH auffindbar ist:

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

Der Installer erkennt oder kann explizit Codex, Claude Code, OpenClaw, Antigravity, Gemini CLI, OpenCode, Cursor, Windsurf, VS Code, Pi, Cline, Zed und Goose konfigurieren. Verwenden Sie --client generic, um eine portable JSON-Konfiguration für einen anderen stdio-fähigen Agenten auszugeben:

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

Der Setup-Befehl schreibt nur den ausgewählten MCP-Eintrag, erstellt ein einmaliges .boxes-mcp.bak-Backup, bevor eine bestehende Konfiguration geändert wird, verwendet atomaren Ersatz und installiert niemals Betriebssystempakete oder ändert VM-Definitionen. Starten Sie den konfigurierten Agenten oder das Harness nach dem Setup neu. Führen Sie boxes-mcp doctor aus, um Node, virsh und erkannte Hosts zu überprüfen.

Optionale Host-Einstellungen können während des Setups gespeichert werden:

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

Der native SPICE-Helfer wird nicht als universelle Binärdatei gebündelt. Erstellen Sie ihn auf einem kompatiblen Linux-Host, nachdem Sie die SPICE/libvirt-Entwicklungspakete des Hosts installiert haben, und übergeben Sie dann seinen geprüften absoluten Pfad mit --spice-helper oder BOXES_SPICE_HELPER.

Installation aus dem Quellcode

# 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

Konfiguration

Für eine manuelle Einrichtung fügen Sie den Server zu Ihrer Claude-Code-Konfiguration (~/.claude.json) hinzu:

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

Verfügbare Tools

VM-Verwaltung

Snapshot-Verwaltung

Anzeige und Interaktion

Interaktionstools akzeptieren niemals Shell-Fragmente, rohes QMP-JSON, beliebige virsh-Flags, Gastbefehle oder beliebige Transferziele. Neue Operationen erfordern eine laufende Domäne und geben einen stabilen Fähigkeits-/Fehlercode zurück, wenn ihr Backend nicht verfügbar ist.

Optionale Umgebungsvariablen

BOXES_TRANSFER_ROOT ist bewusst erforderlich und wird nicht abgeleitet. Pfade werden kanonisiert, und Symlink-Ausbrüche, Verzeichnisse und spezielle Dateien werden abgelehnt.

boxes.capabilities meldet beobachtete Zustände. Die Konfiguration allein wird nicht als verbunden behandelt: Verwenden Sie probeQmp: true und/oder probeSpice: true, wenn ein externer Status-Probe erforderlich ist. SPICE- Zwischenablage und -Transfer erfordern einen verbundenen Gast-Agenten; boxes.drag_drop meldet applicationAccepted: "unknown", sofern nicht ein externes Viewer-Harness Anwendungsebene-Evidenz liefert.

Die Tastatureingabe verwendet einen festen Linux-virsh-Codesatz. Öffentliche Tastennamen sind case-insensitiv und werden in Großbuchstaben kanonisiert, aber jede Taste darf nur einmal pro begrenztem Akkord vorkommen. Die Whitelist lautet: ALT, BACKSPACE, CAPSLOCK, CTRL, DELETE, DIGIT_0 bis DIGIT_9, DOWN, END, ENTER, ESC, ESCAPE, F1 bis F12, HOME, INSERT, LEFT, META, NUMLOCK, PAGEDOWN, PAGEUP, PAUSE, PRINT, RIGHT, SHIFT, SPACE, SUPER, TAB, UP und A bis Z. Das Tastaturlayout des Gasts bestimmt das resultierende Zeichen; die Tasten-Whitelist garantiert keinen Text unabhängig von diesem Layout.

Anwendungsbeispiele

Mit 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]

Direkte Verwendung

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

Entwicklung

Projektstruktur

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

Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Lokale Testabdeckung: Der aktuelle Checkout führt 95 bestandene Tests und 9 gesperrte Live-Tests aus, die standardmäßig übersprungen werden. Die Standard-Suite kann ohne libvirt-Zugriff sicher ausgeführt werden.

• exec.ts: 100 % Anweisungen

• libvirt.ts: 81,3 % Anweisungen, 92,85 % Verzweigungen

• Interaktionsvalidierung, Befehlsaufbau, QMP-Antwortzuordnung, Artefaktbereinigung, Helfer-Framing, Fähigkeitserkennung und Pfad-Eingrenzungstests

Führen Sie die expliziten lokalen Prüfungen des nativen Helferprozesses aus mit:

npm run test:spice-helper

Führen Sie die Suite für Wegwerf-VMs nur mit allen drei Sicherheitsvariablen aus:

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

Die Live-Suite wählt niemals eine aufgeführte VM aus, ändert VM-Definitionen oder stoppt selbst einen Gastdienst. Die Abdeckung der Gast-Agenten-Trennung erfordert, dass der Bediener spice-vdagent im explizit wegwerfbaren Gast manuell trennt und BOXES_TEST_AGENT_DISCONNECTED=1 hinzufügt; tun Sie dies niemals bei einem nicht wegwerfbaren Gast.

Die Standard-Suite ist gemockt/lokal: Sie beweist nicht, dass QMP, SPICE, Zwischenablage oder Drag-and-Drop gegen eine echte VM funktioniert. Live-Tests müssen opt-in sein und auf eine spezifisch benannte Wegwerf-VM mit Snapshots abzielen; keine beliebige zuerst aufgeführte Domain wird jemals von den Interaktionswerkzeugen ausgewählt.

Erstellen

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Optionaler systemd-Benutzerdienst

Die eingecheckte Unit ist für einen Quellcode-Checkout gedacht. Sie wird nicht benötigt, wenn der Server von der MCP-Konfiguration eines Agents gestartet oder global mit npm installiert wird. Installieren Sie ihn als Benutzerdienst für den automatischen Start nach dem Erstellen des Checkouts:

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

Sicherheitsüberlegungen

• ✅ Sandbox-Ausführung: Verwendet Node.js execFile mit Timeout- und Puffergrenzen

• ✅ Keine beliebigen Befehle: Nur vordefinierte virsh-Operationen sind erlaubt

• ✅ Typisierte Eingabegrenze: QMP-Befehle und SPICE-Operationen sind interne Enums mit validierten Argumenten

• ✅ Begrenzte Nutzlasten: Tastenanzahl, Haltedauern, Koordinaten, Scroll-Deltas, Screenshots, Zwischenablage und Übertragungen sind begrenzt

• ✅ Pfadeingrenzung: Drag/Drop-Quellen müssen nach der Kanonisierung unter BOXES_TRANSFER_ROOT bleiben

• ✅ Speichererhaltung: VM-Speicher wird standardmäßig nicht gelöscht

• ✅ LIBVIRT_URI-Isolation: Respektiert die umgebungsangegebene libvirt-Verbindung

• ⚠️ Erforderliche Berechtigungen: Der Benutzer muss Mitglied der libvirt-Gruppe sein

• ⚠️ Netzwerkexposition: Nicht für den Fernzugriff ohne zusätzliche Sicherheit ausgelegt

• ⚠️ Erweiterte Steuerungsoberfläche: Screenshots und Gast-Zwischenablagedaten sind nicht vertrauenswürdig; halten Sie den MCP-Server auf lokalem stdio

• ⚠️ SPICE-Helper-Vertrauen: Die Hilfsprogrammdatei ist eine explizite Host-Abhängigkeit und darf keine Anmeldeinformationen, Zwischenablageinhalte oder Dateiinhalte protokollieren

SPICE-Helper-Protokoll

Der TypeScript-Server startet einen persistenten Helper-Unterprozess und sendet zeilengetrennte Version-1-JSON-Anfragen über stdin, wobei Antworten über die Anfrage-ID korreliert werden. Der Helper wird mit einem expliziten ausführbaren Pfad und ohne vom Aufrufer kontrollierte Argumente aufgerufen. Die Anfragehülle sieht wie folgt aus:

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

Unterstützte Operationsnamen sind intern (status, mouse, clipboard.read, clipboard.write, file.transfer und drag-drop). Ein Helper-Fehler wird auf einen stabilen MCP-Fehler wie SPICE_AGENT_DISCONNECTED, SPICE_CAPABILITY_MISSING oder SPICE_UNAVAILABLE abgebildet. Nutzlasten, Zeilen, ausstehende Anfragen, Übertragungsgrößen, Zwischenablage- Bytes und Operationszeit sind begrenzt. Fortschrittsereignisse schließen eine Anfrage nie ab. Der Helper protokolliert keine Zwischenablageinhalte, Dateiinhalte, SPICE-Tickets oder Anmeldeinformationen.

Fähigkeitsmatrix

Die Zwischenablageunterstützung hängt von der Desktop-Integration des Gasts ab. Der aktuelle SPICE-Gast- Agent ist X11-orientiert, daher können Wayland-Gäste wie Hyprland/Omarchy SPICE_CAPABILITY_MISSING melden, selbst wenn spice-vdagent installiert und ausgeführt wird. Maus und Dateiübertragung können weiterhin unabhängig funktionieren.

Fehlerbehebung

Keine VMs aufgelistet

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

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

Berechtigung verweigert

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

VMs werden in Boxes nicht angezeigt

Öffnen Sie virt-manager und prüfen Sie, welche Verbindung Ihre VMs verwenden:

• Systemverbindung: qemu:///system

• Benutzersitzung: qemu:///session

Setzen Sie die Umgebungsvariable LIBVIRT_URI entsprechend.

SPICE-Fähigkeitsfehler

Wenn virsh domdisplay No graphical display found meldet und die Domain-XML <graphics type='spice'><listen type='none'/></graphics> enthält, ist das eine beabsichtigte libvirt-Konfiguration ohne öffentlichen Listener. Erfinden Sie keinen Port und ändern Sie die VM- Definition nicht nur, um eine Viewer-URI zu erhalten. Mit dem konfigurierten nativen Helper verwendet boxes-mcp den internen spice+libvirt-fd://local-Transport und fragt libvirt nach einem Grafik- FD für jeden SPICE-Kanal. Der Helper muss dieselbe libvirt-Verbindung wie der MCP-Prozess verwenden:

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

Die Domain muss ausgeführt werden, der Helper muss gegen libvirt und spice-client-glib verlinkt sein, und der Gast muss den virtio-SPICE-Agent-Kanal bereitstellen. Ein verbundener Agent kann dennoch keine Zwischenablagefähigkeit haben; überprüfen Sie boxes.capabilities mit probeSpice: true, anstatt die Unterstützung allein aus der XML abzuleiten.

Verwenden Sie boxes.capabilities mit probeSpice: true und überprüfen Sie den zurückgegebenen Zustand:

• configured: Ein überprüfter Helper und SPICE-Endpunkt sind konfiguriert, aber ein Verbindungs- nachweis wurde nicht angefordert;

• connecting: Der Helper beobachtete einen unvollständigen Kanalsatz;

• connected: Die erforderlichen Kanäle sind verbunden;

• agent-disconnected: Der Gast-Agent ist nicht verbunden;

• capability-missing: Die Backend-, Kanal-, Helper- oder Gast-Fähigkeit fehlt.

Zum Beispiel ist ein verbundener Gast-Agent, der Dateiübertragung unterstützt, aber keine Zwischenablage ankündigt, capability-missing, nicht agent-disconnected. Um die Zwischenablage zu aktivieren, muss der Gast den spice-vdagent-Dienst seiner Distribution installiert haben, in der Desktop-Sitzung ausgeführt werden und über den virtio-SPICE-Agent-Kanal verbunden sein. Auf einem Wayland/Hyprland-Desktop überprüfen Sie, ob der Agent der Distribution diesen Compositor tatsächlich unterstützt; ein aktiver Dienst allein ist kein Beweis. Der Live-Omarchy-Gast hatte spice-vdagent 0.23.0-1 und einen aktiven Benutzerdienst, protokollierte jedoch xrandr output ID NOT FOUND und keinen Besitzer für org.gnome.Mutter.DisplayConfig, daher gab boxes-mcp korrekt SPICE_CAPABILITY_MISSING zurück. Verwenden Sie eine X11-Gastsitzung für den aktuellen Upstream-Agenten oder stellen Sie eine separat validierte Wayland-Zwischenablagebrücke bereit. Der Server installiert keine Gastpakete und startet keine Gastdienste automatisch.

Der persistente SPICE-Client akzeptiert auch ein Abbruchsignal. Die Abbrechung beendet den aktuellen Helper-Prozess, schlägt alle ausstehenden Operationen deterministisch fehl und ermöglicht der nächsten Anfrage, eine saubere Sitzung zu erstellen; dies wird als OPERATION_CANCELLED gemeldet.

Überprüfen Sie die Host-Abhängigkeiten und den Helper direkt, ohne Eingaben an eine VM zu senden:

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

Der lokale Protokolltest des Helpers verbindet sich absichtlich mit 127.0.0.1:1 und erwartet ein typisiertes nicht verfügbares/getrenntes Ergebnis. Das ist kein Live-SPICE-Beweis.

Roadmap

• VM-Erstellung über virt-install-Integration

• Netzwerkverwaltung (virsh net-list, Portweiterleitung)

• Speicherpool-Informationen (virsh vol-list)

• VM-Import aus OVA/QCOW2

• Unterstützung für Remote-libvirt-Verbindungen

• Leistungsmetriken und Überwachung

Mitwirken

Beiträge sind willkommen! Bitte lesen Sie CONTRIBUTING.md für Richtlinien.

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)

3. Führen Sie Tests aus (npm test)

4. Committen Sie Änderungen (git commit -m 'Add amazing feature')

5. Pushen Sie den Branch (git push origin feature/amazing-feature)

6. Öffnen Sie einen Pull Request

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe die Datei LICENSE für Details.

Danksagungen

• Entwickelt für Claude Code

• Verwendet Model Context Protocol SDK

• Integriert mit der libvirt-Virtualisierungs-API

Unterstützung

• Probleme: GitHub Issues

• Diskussionen: GitHub Discussions

• Dokumentation: Projekt-Wiki

Mit ❤️ für die Claude Code-Community erstellt