boxes-mcp CLAUDE.md

Claude Code MCP Server – GNOME Boxes (via libvirt)

A lightweight Model Context Protocol (MCP) server that lets Claude Code manage virtual machines created/managed by GNOME Boxes (which uses libvirt/QEMU under the hood). It exposes safe, task‑oriented tools for listing, starting, stopping, snapshotting, and inspecting VMs.

Works on Ubuntu 22.04/24.04 with libvirt. Requires the user running Claude Code to be in the libvirt (and often kvm) groups.

---

🗂️ Project Layout

boxes-mcp/
├─ package.json
├─ tsconfig.json
├─ src/
│  ├─ index.ts            # MCP server entry – registers tools
│  ├─ exec.ts             # thin wrapper for running shell commands safely
│  └─ libvirt.ts          # libvirt/virsh helpers & parsers
├─ README.md
└─ systemd/
   └─ boxes-mcp.service   # optional: run server as a user service

---

package.json

{
  "name": "boxes-mcp",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "description": "Claude Code MCP server for GNOME Boxes (libvirt/virsh)",
  "license": "MIT",
  "scripts": {
    "build": "tsc -p .",
    "start": "node dist/src/index.js",
    "dev": "node --watch dist/src/index.js",
    "compile": "tsc -p ."
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.2.0"
  },
  "devDependencies": {
    "@types/node": "^22.7.5",
    "typescript": "^5.6.3"
  }
}

---

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "Bundler",
    "outDir": "dist",
    "rootDir": ".",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

---

src/exec.ts

import { execFile } from "node:child_process";
import { promisify } from "node:util";

const pexec = promisify(execFile);

export type ExecResult = { stdout: string; stderr: string };

export async function sh(
  cmd: string,
  args: string[],
  opts: { timeoutMs?: number; env?: NodeJS.ProcessEnv } = {}
): Promise<ExecResult> {
  const { timeoutMs = 60_000, env = process.env } = opts;
  const { stdout, stderr } = await pexec(cmd, args, {
    timeout: timeoutMs,
    env,
    maxBuffer: 10 * 1024 * 1024
  });
  return { stdout: stdout.toString(), stderr: stderr?.toString() ?? "" };
}