docker-vm-mcp

Erstellt von sundar.

Ein MCP-Server, der einem KI-Agenten die vollständige Kontrolle über den VM-Lebenszyklus gibt – Erstellen, SSH-Login, Befehle ausführen, Stoppen/Starten/Neustarten, Löschen, Logs und Ressourcenstatistiken – über leichte „VMs“, die auf Docker-Containern basieren. Jede VM ist ein echtes Ubuntu-System, auf dem ein echter sshd läuft, mit sudo und einem persistenten Datenträger, sodass sie sich wie eine normale Box verhält, in die du dich einloggen kannst – kein Cloud-Konto und keine verschachtelte Virtualisierung erforderlich. Der Server selbst ist containerisiert, wird als Docker-Image veröffentlicht und vollständig über das Model Context Protocol gesteuert.

Sobald das eingerichtet ist, kannst du Claude einfach Dinge fragen wie:

• „Erstelle eine VM namens dev-box mit 2 CPUs und 2 GB RAM“

• „Verschaffe mir SSH-Zugang zu dev-box“ / „Wie lautet der SSH-Login für dev-box?“

• „Installiere nginx auf dev-box und starte es“

• „Stoppe dev-box“ / „Lösche dev-box“

• „Liste alle meine VMs auf“

und Claude wird den gesamten Lebenszyklus über die unten aufgeführten Tools steuern.

Wie es funktioniert

Jede „VM“ ist ein Docker-Container, der aus einem kleinen Ubuntu-22.04-Image (vm-image/Dockerfile) erstellt wird, einen echten sshd ausführt, über sudo verfügt und ein benanntes Docker-Volume als Home-Verzeichnis eingehängt bekommt (damit Dateien Stopp/Neustart überleben, ähnlich wie ein EBS-Volume, das an einer EC2-Instanz hängt). Der MCP-Server selbst kommuniziert über /var/run/docker.sock mit deinem lokalen Docker-Daemon – er führt keine VMs selbst aus, sondern steuert deine vorhandene Docker-Desktop-Installation.

Claude  <--MCP/stdio-->  docker-vm-mcp container  <--docker.sock-->  Docker Desktop
                                                                          |
                                                                    vm-dev-box (Ubuntu + sshd)
                                                                    vm-staging (Ubuntu + sshd)
                                                                    ...

Related MCP server: Docker MCP Server

Voraussetzungen

• Docker Desktop muss auf deinem Mac installiert sein und laufen

• Node.js 20+ nur, wenn du den Server außerhalb von Docker ausführen möchtest (nicht erforderlich)

1. Erstellen

Aus diesem Ordner:

docker build -t docker-vm-mcp:latest .

Dies erstellt nur das MCP-Server-Image. Das VM-Basisimage (docker-vm-mcp/vm-base:latest) wird automatisch beim ersten Aufruf von vm_create erstellt – der Server enthält vm-image/Dockerfile und baut es bei der ersten Verwendung gegen deinen Docker-Daemon. Du kannst es auch selbst vorab erstellen:

docker build -t docker-vm-mcp/vm-base:latest ./vm-image

2. Ausführen / Registrieren bei Claude Desktop

MCP-Server über stdio werden vom Client (Claude Desktop) gestartet, nicht eigenständig ausgeführt. Füge dies zu deiner Claude-Desktop-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "docker-vm-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "docker-vm-mcp-state:/data",
        "docker-vm-mcp:latest"
      ]
    }
  }
}

Starte dann Claude Desktop neu. Beide Mounts sind erforderlich:

• /var/run/docker.sock – ermöglicht dem Server, VM-Container auf deinem Rechner zu erstellen, zu starten, zu stoppen und darin Befehle auszuführen (exec).

• docker-vm-mcp-state (ein benanntes Volume) – hier speichert der Server das generierte SSH-Passwort jeder VM über Neustarts hinweg. Ohne dieses Volume verliert vm_ssh_info gespeicherte Passwörter, sobald der MCP-Server-Container neu startet (die VM-Container selbst sind nicht betroffen – sie laufen weiter).

Du kannst überprüfen, dass das Image läuft und Docker erreichen kann, bevor du es in Claude Desktop einbindest:

docker run -i --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v docker-vm-mcp-state:/data \
  docker-vm-mcp:latest
# should print nothing and just wait on stdin (that's correct — it's
# speaking MCP, not a REPL). Ctrl+C to exit.

Tools, die dieser Server bereitstellt

Selbst einloggen

Jede VM bindet ihren SSH-Port an deinen Mac, sodass du dich, sobald Claude eine erstellt hat, auch direkt von einem Terminal aus per SSH einloggen kannst:

ssh vmuser@localhost -p <port>   # port and password from vm_create / vm_ssh_info

Übergib sshPublicKey an vm_create (den Inhalt deiner ~/.ssh/id_ed25519.pub), um das Passwort zu überspringen und dich stattdessen mit deinem Schlüssel einzuloggen.

Dieses Image veröffentlichen

Um es zu teilen (z. B. damit ein Teammitglied oder ein anderer Rechner einfach docker pull ausführen kann, statt aus dem Quellcode zu bauen):

docker tag docker-vm-mcp:latest <your-dockerhub-username>/docker-vm-mcp:latest
docker push <your-dockerhub-username>/docker-vm-mcp:latest

In das Image ist nichts Geheimes eingebacken – Anmeldeinformationen werden zur Laufzeit pro VM generiert und nur im lokalen docker-vm-mcp-state-Volume auf der Maschine gespeichert, die den Container ausführt. Es ist sicher, es zu veröffentlichen.

Sicherheitshinweise (lies dies, bevor du es über deinen eigenen Rechner hinaus verfügbar machst)

• Der Docker-Socket-Mount ist äquivalent zu Root-Rechten. Alles, was Zugriff auf /var/run/docker.sock hat, kann jeden Container auf deinem Rechner steuern, nicht nur die VMs, die dieses Tool erstellt. Führe dieses Image mit diesem Mount nur auf einer Maschine aus, der du vertraust, und setze den MCP-Server selbst (oder einen Port zu ihm) niemals unvertrauenswürdigen Aufrufern aus.

• SSH-Passwörter werden im Klartext gespeichert im docker-vm-mcp-state-Volume (/data/credentials.json), damit vm_ssh_info sie dir später zurückgeben kann. Das ist für ein persönliches lokales Entwicklungs-Tool in Ordnung; verwende dies nicht für Multi-Tenant- oder Produktionszwecke, ohne es abzuhärten (z. B. auf reine Schlüssel-Authentifizierung umzustellen und keine Passwörter mehr zu speichern).

• VM-Container veröffentlichen ihren SSH-Port standardmäßig auf 0.0.0.0 (Docker-Standard), was bedeutet, dass andere Geräte in deinem lokalen Netzwerk ihn erreichen könnten, wenn deine Firewall das zulässt. Übergib einen expliziten sshPort und sichere ihn per Firewall ab, oder binde nur an 127.0.0.1, falls das für dich relevant ist (ändere die Host-IP der PortBindings in src/tools/createVm.ts auf 127.0.0.1 und baue neu).

Praxisnahe Validierung: ServiceNow Discovery

Dieses Projekt wurde als Live-Discovery-Ziel für eine echte ServiceNow-Instanz verwendet, über einen lokal ausgeführten MID Server (ebenfalls dockerisiert) – ein Beweis, dass es sich wie ein echter per SSH erreichbarer Linux-Host verhält, nicht nur wie ein Spielzeug:

• Standard Discovery – MID Server → VM über die LAN-IP des Macs und den veröffentlichten SSH-Port der VM (z. B. 192.168.x.x:<port>) – hat erfolgreich ein cmdb_ci_linux_server-CI mit Hostname, OS, RAM und CPU-Details erstellt, die live über SSH abgerufen wurden.

• Quick Discovery funktioniert ebenfalls auf dieselbe Weise.

• Da der MID-Server-Container und der VM-Container beide im standardmäßigen bridge-Netzwerk von Docker liegen, können sie sich alternativ auch direkt über die interne Container-IP auf dem Standard-SSH-Port (22) erreichen – kein veröffentlichter Port nötig und keine Abhängigkeit von der LAN-IP des Macs (die sich zwischen Netzwerken ändert).

• Eine Eigenheit, die du wissen solltest, wenn du das selbst ausprobierst: Der ermittelte CPU-Hersteller wird als „Apple“ angezeigt. Das ist korrekt, kein Fehler – Docker Desktop für Mac führt Container in einer linuxkit-VM aus, die direkt auf dem Apple-Silicon-Chip des Hosts bootet. SSH-Abfragen, die /proc/cpuinfo lesen, sehen daher die darunterliegende echte Hardware, genau wie auf jedem anderen Host.

Projektstruktur

docker-vm-mcp/
├── Dockerfile              # MCP server image
├── package.json
├── tsconfig.json
├── vm-image/
│   └── Dockerfile          # base "VM" image (Ubuntu + sshd), built on first vm_create
└── src/
    ├── index.ts            # MCP server entrypoint (stdio transport)
    ├── docker.ts            # Docker client, image-build, container lookup helpers
    ├── state.ts             # local credential store (/data/credentials.json)
    ├── util.ts              # exec/log demuxing helpers
    └── tools/
        ├── createVm.ts
        ├── listVms.ts
        ├── startVm.ts
        ├── stopVm.ts
        ├── restartVm.ts
        ├── deleteVm.ts
        ├── execVm.ts
        ├── sshInfo.ts
        ├── setPassword.ts
        ├── logsVm.ts
        └── statsVm.ts

Eine Anmerkung dazu, wie dies verifiziert wurde

Dies wurde in einer Sandbox-Umgebung ohne Zugriff auf die npm-Registry erstellt und typgeprüft, daher konnten npm install / npm run build hier nicht durchgängig ausgeführt werden. Der TypeScript-Code wurde gegen Nodes eigene Typdefinitionen geprüft, ohne Fehler; die einzigen verbleibenden Prüfungen betreffen die eigenen Typen von @modelcontextprotocol/sdk, dockerode und zod, die in dieser Sandbox nicht installierbar waren. Führe dies einmal aus, nachdem du das Projekt auf deinen Mac kopiert hast, vor deinem ersten docker build:

npm install
npm run build

Wenn tsc etwas meldet, das über das oben bereits Behandelte hinausgeht, handelt es sich höchstwahrscheinlich um eine versionsspezifische API-Änderung in @modelcontextprotocol/sdk (ein sich schnell weiterentwickelndes Paket) – die Lösung ist fast immer eine kleine Anpassung der Importpfade in src/index.ts (@modelcontextprotocol/sdk/server/mcp.js / .../server/stdio.js), damit sie der Version entsprechen, die npm install aufgelöst hat.