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)
                                                                    ...

Related MCP server: Docker MCP Server

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

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.

You can also run any of the vm_* tools by hand in Terminal — they're all thin wrappers around plain docker commands, nothing they do requires Claude or an MCP client:

Resource limits, explained

RAM, CPU, and disk aren't dedicated hardware per VM the way they would be on a real hypervisor or a cloud instance — they're all drawn from Docker Desktop's own VM, which itself has a fixed allocation on your Mac (see Docker Desktop → Settings → Resources). Every container you run, including every VM this server creates, shares that one pool.

• RAM / CPU: passing memoryMb/cpus to vm_create sets a ceiling for that VM, not a reservation — an idle VM isn't holding that memory hostage, but the ceiling can't exceed what Docker Desktop's VM has been allocated in the first place. If you ask for more than Docker Desktop itself has, you'll hit memory pressure across everything else running in Docker, not get more RAM from nowhere.

• You don't need to delete and recreate a VM to change its limits (which would lose its SSH port and break anything pointed at it, like a ServiceNow Discovery Schedule) — resize a running one live instead:

  docker update --memory 8g --memory-swap 8g vm-dev-box
  docker update --cpus 4 vm-dev-box

• Disk works the same way: df -h inside a VM shows Docker Desktop's whole virtual disk (often ~1TB, configurable in the same Settings panel), not a disk assigned to that VM specifically. vm_create doesn't set a disk quota per VM, so nothing stops one VM from filling the entire shared pool if it writes a lot of data.

• CPU/vendor info reported by a VM (e.g. lscpu, /proc/cpuinfo) is your Mac's real hardware, not a virtualized/generic value — Docker Desktop's Linux VM boots directly on the host CPU, so on Apple Silicon a VM will correctly report an Apple ARM CPU, not an emulated x86 one.

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.