docker-vm-mcp

Built by sundar.

An MCP server that gives an AI agent full VM lifecycle control — create, SSH login, exec commands, stop/start/restart, delete, logs, and resource stats — over lightweight "VMs" backed by Docker containers. Each VM is a real Ubuntu system running an actual sshd, with sudo and a persistent disk, so it behaves like a normal box you can log into — no cloud account and no nested virtualization required. The server itself is containerized and published as a Docker image, and is driven entirely through the Model Context Protocol.

Once this is set up you can just ask Claude things like:

• "Create a VM called dev-box with 2 CPUs and 2GB RAM"
• "SSH me into dev-box" / "What's the SSH login for dev-box?"
• "Install nginx on dev-box and start it"
• "Stop dev-box" / "Delete dev-box"
• "List all my VMs"

and Claude will drive the whole lifecycle through the tools below.

How it works

Each "VM" is a Docker container built from a small Ubuntu 22.04 image (vm-image/Dockerfile) that runs a real sshd, has sudo, and gets a named Docker volume mounted as its home directory (so files survive stop/restart, similar to an EBS volume attached to an EC2 instance). The MCP server itself talks to your local Docker daemon over /var/run/docker.sock — it does not run VMs itself, it drives your existing Docker Desktop installation.

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

Prerequisites

• Docker Desktop installed and running on your Mac
• Node.js 20+ only if you want to run the server outside Docker (not required)

1. Build

From this folder:

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

This builds only the MCP server image. The VM base image (docker-vm-mcp/vm-base:latest) is built automatically the first time you call vm_create — the server bundles vm-image/Dockerfile and builds it against your Docker daemon on first use. You can also pre-build it yourself:

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

2. Run / register with Claude Desktop

MCP servers over stdio are launched by the client (Claude Desktop), not run standalone. Add this to your Claude Desktop config (~/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"
      ]
    }
  }
}

Then restart Claude Desktop. The two mounts are both required:

• /var/run/docker.sock — lets the server create/start/stop/exec into VM containers on your machine.
• docker-vm-mcp-state (a named volume) — where the server remembers each VM's generated SSH password across restarts. Without it, vm_ssh_info loses saved passwords whenever the MCP server container restarts (the VM containers themselves are unaffected — they keep running).

You can sanity-check the image runs and can reach Docker before wiring it into Claude Desktop:

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 this server exposes

Tool	What it does
vm_create	Create + start a new VM. Params: name, cpus, memoryMb, sshPort, sshUser, sshPublicKey. Returns the SSH command and generated password.
vm_list	List all managed VMs with status and SSH port.
vm_start	Start a stopped VM.
vm_stop	Stop a running VM (disk is preserved).
vm_restart	Reboot a VM.
vm_delete	Permanently delete a VM (and its disk volume, unless removeVolume=false).
vm_exec	Run a shell command inside a VM directly via Docker (no SSH needed).
vm_ssh_info	Get the SSH command, host, port, user, and password for a VM.
vm_set_password	Set or regenerate a VM's SSH password (also resyncs vm_ssh_info after a manual password change).
vm_logs	Tail a VM's console/system log output.
vm_stats	Live CPU % / memory usage for a running VM.

Logging in yourself

Every VM binds its SSH port to your Mac, so once Claude creates one you can also just SSH in directly from a terminal:

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

Pass sshPublicKey to vm_create (your ~/.ssh/id_ed25519.pub contents) to skip the password and log in with your key instead.

Publishing this image

To share it (e.g. so a teammate or another machine can just docker pull instead of building from source):

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

Nothing secret is baked into the image — credentials are generated per-VM at runtime and stored only in the local docker-vm-mcp-state volume on whichever machine runs the container. It's safe to publish.

Security notes (read before exposing this beyond your own machine)

• The Docker socket mount is root-equivalent. Anything with access to /var/run/docker.sock can control every container on your machine, not just the VMs this tool creates. Only run this image with that mount on a machine you trust, and never expose the MCP server itself (or a port to it) to untrusted callers.
• SSH passwords are stored in plaintext in the docker-vm-mcp-state volume (/data/credentials.json) so vm_ssh_info can hand them back to you later. That's fine for a personal local dev tool; don't repurpose this for multi-tenant or production use without hardening it (e.g. switch to key-only auth and stop persisting passwords).
• VM containers publish their SSH port on 0.0.0.0 by default (Docker's default), meaning other devices on your local network could reach it if your firewall allows it. Pass an explicit sshPort and firewall it, or bind to 127.0.0.1 only, if that matters to you (edit the PortBindings host IP in src/tools/createVm.ts to 127.0.0.1 and rebuild).

Real-world validation: ServiceNow Discovery

This project has been used as a live Discovery target for a real ServiceNow instance, via a locally-run MID Server (also Dockerized) — proof it behaves like a genuine SSH-reachable Linux host, not just a toy:

• Standard Discovery, MID Server → VM over the Mac's LAN IP and the VM's published SSH port (e.g. 192.168.x.x:<port>) — successfully created a cmdb_ci_linux_server CI with hostname, OS, RAM, and CPU details pulled live over SSH.
• Quick Discovery also works the same way.
• Since the MID Server container and the VM container both sit on Docker's default bridge network, they can alternatively reach each other directly by internal container IP on the standard SSH port (22) — no published port needed, and no dependency on the Mac's LAN IP (which changes across networks).
• One quirk worth knowing if you try this yourself: discovered CPU manufacturer shows as "Apple". That's correct, not a bug — Docker Desktop for Mac runs containers inside a linuxkit VM booted directly on the host's own Apple Silicon chip, so SSH probes reading /proc/cpuinfo see the real hardware underneath, the same as they would on any other host.

Project structure

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

A note on how this was verified

This was built and type-checked in a sandboxed environment without access to the npm registry, so npm install / npm run build could not be run end-to-end here. The TypeScript was checked against Node's own type definitions with no errors; the only remaining checks are against @modelcontextprotocol/sdk, dockerode, and zod's own types, which weren't installable in that sandbox. Run this once after copying the project to your Mac, before your first docker build:

npm install
npm run build

If tsc reports anything beyond what's already handled above, it's most likely a version-specific API shift in @modelcontextprotocol/sdk (it's a fast-moving package) — the fix is almost always a small adjustment to the import paths in src/index.ts (@modelcontextprotocol/sdk/server/mcp.js / .../server/stdio.js) to match whatever version npm install resolved.