# docker-vm-mcp

Built by [sundar](https://github.com/suvenkat79).

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:

```bash
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:

```bash
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`):

```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:

```bash
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:

```bash
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:

| Tool | Terminal equivalent |
|---|---|
| `vm_list` | `docker ps -a --filter "label=docker-vm-mcp.managed=true" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"` |
| `vm_start` | `docker start vm-<name>` |
| `vm_stop` | `docker stop vm-<name>` |
| `vm_restart` | `docker restart vm-<name>` |
| `vm_delete` | `docker rm -f vm-<name> && docker volume rm vm-<name>-data` |
| `vm_exec` | `docker exec -it vm-<name> bash -lc "<command>"` |
| `vm_logs` | `docker logs vm-<name> --tail 200` |
| `vm_stats` | `docker stats vm-<name> --no-stream` |
| `vm_set_password` | `docker exec vm-<name> bash -lc "echo 'vmuser:newpass' \| chpasswd"` |
| `vm_ssh_info` | `docker run --rm -v docker-vm-mcp-state:/data alpine cat /data/credentials.json` |

## 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:
  ```bash
  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):

```bash
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`:

```bash
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.