boxes-mcp

libvirt/virsh를 통해 GNOME Boxes 가상 머신을 관리할 수 있도록 호환 에이전트와 개발자 하네스를 지원하는 로컬 Model Context Protocol(MCP) 서버입니다. 안전하고 되돌릴 수 있는 VM 작업, 스냅샷, 스크린샷, 제한된 키보드 및 마우스 입력, 기능 게이트 SPICE 기능을 제공합니다.

이 프로젝트는 의도적으로 GNOME Boxes의 Linux libvirt/QEMU 스택을 대상으로 합니다. VMware와 VirtualBox는 현재 지원되지 않습니다. 해당 제품의 디스플레이, 입력, 게스트 에이전트, 클립보드, 드래그 앤 드롭 API는 신뢰 및 기능 계약이 다르므로 libvirt 구현에서 추론하지 말고 별도의 증거 기반 공급자로 추가해야 합니다.

Contents

• 설치

• 구성

• 사용 가능한 도구

• 사용 예제

• 개발

• 문제 해결

• 보안 고려 사항

Related MCP server: kwin-mcp

Features

• 🖥️ VM 수명 주기 관리 - VM 시작, 중지, 재부팅, 일시 중지 및 재개

• 📸 스냅샷 작업 - VM 스냅샷 생성, 나열, 되돌리기 및 삭제

• 🔍 VM 검색 - 모든 VM을 상세 정보와 함께 나열 및 검사

• 🔒 안전한 작업 - 기본적으로 스토리지 보존, 파괴적 작업 없음

• 🎯 GNOME Boxes 호환 - GNOME Boxes VM과 완벽하게 작동

• 🖱️ 제어된 상호 작용 - 스크린샷, 허용 목록 키보드, 입력된 마우스 도구

• 🔌 기능 게이트 SPICE - SPICE 입력, 클립보드 및 전송을 위한 선택적 네이티브 헬퍼 프로토콜

• ⚡ 빠르고 가벼움 - 최소 오버헤드, 직접 virsh 통합

Installation

Host prerequisites

• Ubuntu 22.04/24.04 (또는 호환되는 Linux 배포판)

• libvirt-daemon-system, qemu-kvm 설치

• Node.js 18+ 및 npm

• libvirt 및 kvm 그룹의 사용자

• 수명 주기, 스크린샷, 키보드 및 QMP 대체 작업을 위해 PATH에 virsh 사용 가능

SPICE 지원 도구는 추가로 SPICE 디스플레이, 게스트 virtio-serial 에이전트 채널, 실행 중인 spice-vdagent(또는 이에 상응하는 게스트 에이전트)가 필요합니다. 클립보드 지원은 해당 에이전트가 제공하는 게스트 데스크톱 통합에도 의존합니다. 표준 spice-vdagent 세션 구성 요소는 X11 지향적입니다. Wayland/Hyprland 게스트는 패키지와 서비스가 실행 중이더라도 클립보드에 대해 capability-missing을 보고할 수 있습니다. 호스트가 spice-client-glib, json-glib 및 GLib 개발 파일을 제공하는 경우에만 선택적 네이티브 헬퍼를 빌드하세요. 그래픽 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 서버만 설치합니다. 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, 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

구성

수동 설정의 경우 서버를 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 플래그, 게스트 명령 또는 임의의 전송 대상을 허용하지 않습니다. 새 작업은 실행 중인 도메인이 필요하며 백엔드를 사용할 수 없을 때 안정적인 기능/오류 코드를 반환합니다.

선택적 환경 변수

BOXES_TRANSFER_ROOT는 추론되지 않고 의도적으로 필요합니다. 경로는 정규화되며 심볼릭 링크 이스케이프, 디렉터리 및 특수 파일은 거부됩니다.

boxes.capabilities는 관찰된 상태를 보고합니다. 구성만으로는 연결된 것으로 간주되지 않습니다. 외부 상태 프로브가 필요한 경우 probeQmp: true 및/또는 probeSpice: true를 사용하세요. SPICE 클립보드 및 전송에는 연결된 게스트 에이전트가 필요합니다. boxes.drag_drop은 외부 뷰어 하네스가 애플리케이션 수준 증거를 제공하지 않는 한 applicationAccepted: "unknown"을 보고합니다.

키보드 입력은 하나의 고정된 Linux virsh 코드셋을 사용합니다. 공개 키 이름은 대소문자를 구분하지 않으며 대문자로 정규화되지만 각 키는 제한된 코드당 한 번만 발생할 수 있습니다. 허용 목록은 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

로컬 테스트 커버리지: 현재 체크아웃은 95개의 통과 테스트와 기본적으로 건너뛰는 9개의 게이트 라이브 테스트를 실행합니다. 기본 스위트는 libvirt 액세스 없이 실행해도 안전합니다.

• exec.ts: 100% 문

• libvirt.ts: 81.3% 문, 92.85% 분기

• 상호 작용 검증, 명령 구성, QMP 응답 매핑, 아티팩트 정리, 헬퍼 프레이밍, 기능 검색 및 경로 제한 테스트

명시적 로컬 네이티브 헬퍼 프로세스 검사를 실행하려면:

npm run test:spice-helper

세 가지 안전 변수를 모두 설정한 상태에서만 일회용 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을 추가해야 합니다. 일회용이 아닌 게스트에는 이 작업을 절대 수행하지 마세요.

기본 스위트는 모의(mocked)/로컬입니다. 실제 VM에 대해 QMP, SPICE, 클립보드 또는 드래그 앤 드롭이 작동한다는 것을 입증하지 않습니다. 라이브 테스트는 옵트인 방식이어야 하며 스냅샷이 있는 특정 이름의 일회용 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 작업은 검증된 인수를 가진 내부 열거형

• ✅ 제한된 페이로드: 키 수, 누름 지속 시간, 좌표, 스크롤 델타, 스크린샷, 클립보드 및 전송이 상한으로 제한됨

• ✅ 경로 격리: 드래그 앤 드롭 소스는 정규화 후 BOXES_TRANSFER_ROOT 아래에 유지되어야 함

• ✅ 스토리지 보존: VM 스토리지는 기본적으로 삭제되지 않음

• ✅ LIBVIRT_URI 격리: 환경에 지정된 libvirt 연결을 존중

• ⚠️ 필요한 권한: 사용자는 libvirt 그룹 구성원이어야 함

• ⚠️ 네트워크 노출: 추가 보안 없이 원격 접근용으로 설계되지 않음

• ⚠️ 확장된 제어 표면: 스크린샷과 게스트 클립보드 데이터는 신뢰할 수 없음. MCP 서버를 로컬 stdio에 유지

• ⚠️ SPICE 헬퍼 신뢰: 헬퍼 실행 파일은 명시적 호스트 종속성이며 자격 증명, 클립보드 내용 또는 파일 내용을 기록해서는 안 됨

SPICE 헬퍼 프로토콜

TypeScript 서버는 하나의 지속적인 헬퍼 자식 프로세스를 시작하고 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만으로 지원 여부를 추론하지 말고 probeSpice: true와 함께 boxes.capabilities를 검사하십시오.

probeSpice: true와 함께 boxes.capabilities를 사용하고 반환된 상태를 검사하십시오:

• configured: 검토된 헬퍼와 SPICE 엔드포인트가 구성되어 있지만 연결 증명이 요청되지 않았습니다.

• connecting: 헬퍼가 불완전한 채널 세트를 관찰했습니다.

• connected: 필요한 채널이 연결되었습니다.

• agent-disconnected: 게스트 에이전트가 연결되지 않았습니다.

• capability-missing: 백엔드, 채널, 헬퍼 또는 게스트 기능이 없습니다.

예를 들어 파일 전송을 지원하지만 클립보드 기능을 알리지 않는 연결된 게스트 에이전트는 agent-disconnected가 아니라 capability-missing입니다. 클립보드를 활성화하려면 게스트에 해당 배포판의 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에 연결하고 타입이 지정된 사용 불가/연결