docker-vm-mcp

sundar가 제작했습니다.

AI 에이전트에게 전체 VM 수명 주기 제어(생성, SSH 로그인, 명령 실행, 중지/시작/재시작, 삭제, 로그, 리소스 통계)를 제공하는 MCP 서버입니다. Docker 컨테이너로 구동되는 가벼운 "VM"을 기반으로 합니다. 각 VM은 실제 sshd가 실행되는 실제 Ubuntu 시스템이며, sudo와 영구 디스크를 갖추고 있어 일반적인 박스처럼 로그인할 수 있습니다. 클라우드 계정이나 중첩 가상화가 필요 없습니다. 서버 자체는 컨테이너화되어 Docker 이미지로 게시되며, 전적으로 Model Context Protocol을 통해 구동됩니다.

이것을 설정하면 Claude에게 다음과 같이 요청할 수 있습니다:

• "dev-box라는 VM을 CPU 2개, RAM 2GB로 생성해 줘"

• "dev-box에 SSH로 접속해 줘" / "dev-box의 SSH 로그인 정보가 뭐야?"

• "dev-box에 nginx를 설치하고 시작해 줘"

• "dev-box 중지" / "dev-box 삭제"

• "내 모든 VM 목록을 보여 줘"

그러면 Claude가 아래 도구들을 통해 전체 수명 주기를 처리합니다.

작동 방식

각 "VM"은 실제 sshd를 실행하고 sudo를 가지며, 명명된 Docker 볼륨이 홈 디렉토리로 마운트된(EC2 인스턴스에 연결된 EBS 볼륨과 유사하게 파일이 중지/재시작 후에도 유지됨) 작은 Ubuntu 22.04 이미지(vm-image/Dockerfile)에서 빌드된 Docker 컨테이너입니다. MCP 서버 자체는 /var/run/docker.sock을 통해 로컬 Docker 데몬과 통신합니다. VM을 직접 실행하는 것이 아니라 기존 Docker Desktop 설치를 구동합니다.

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

사전 요구 사항

• Mac에 Docker Desktop이 설치되어 실행 중이어야 합니다.

• Node.js 20+는 Docker 외부에서 서버를 실행하려는 경우에만 필요합니다(필수 아님).

1. 빌드

이 폴더에서:

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

이것은 MCP 서버 이미지만 빌드합니다. VM 기본 이미지(docker-vm-mcp/vm-base:latest)는 vm_create를 처음 호출할 때 자동으로 빌드됩니다. 서버가 vm-image/Dockerfile을 번들로 포함하고 첫 사용 시 Docker 데몬에 대해 빌드합니다. 직접 미리 빌드할 수도 있습니다:

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

2. Claude Desktop과 함께 실행/등록

stdio 기반 MCP 서버는 독립 실행이 아니라 클라이언트(Claude Desktop)에 의해 시작됩니다. Claude Desktop 구성(~/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"
      ]
    }
  }
}

그런 다음 Claude Desktop을 다시 시작하세요. 두 마운트 모두 필수입니다:

• /var/run/docker.sock — 서버가 사용자 머신에서 VM 컨테이너를 생성/시작/중지/exec할 수 있게 합니다.

• docker-vm-mcp-state (명명된 볼륨) — 서버가 각 VM의 생성된 SSH 비밀번호를 재시작 후에도 기억하는 곳입니다. 이것이 없으면 MCP 서버 컨테이너가 재시작될 때마다 vm_ssh_info가 저장된 비밀번호를 잃게 됩니다(VM 컨테이너 자체는 영향을 받지 않으며 계속 실행됩니다).

Claude Desktop에 연결하기 전에 이미지가 실행되고 Docker에 도달할 수 있는지 확인할 수 있습니다:

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.

이 서버가 노출하는 도구

직접 로그인

각 VM은 SSH 포트를 Mac에 바인딩하므로 Claude가 하나를 생성하면 터미널에서 직접 SSH로 접속할 수도 있습니다:

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

vm_create에 sshPublicKey(사용자의 ~/.ssh/id_ed25519.pub 내용)를 전달하면 비밀번호를 건너뛰고 키로 로그인할 수 있습니다.

이 이미지 게시

공유하려면(예: 팀원이나 다른 머신이 소스에서 빌드하는 대신 docker pull만 하도록):

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

이미지에는 비밀이 내장되어 있지 않습니다. 자격 증명은 런타임에 VM별로 생성되며 컨테이너가 실행되는 머신의 로컬 docker-vm-mcp-state 볼륨에만 저장됩니다. 게시해도 안전합니다.

보안 참고 사항(자신의 머신 밖으로 노출하기 전에 읽어보세요)

• Docker 소켓 마운트는 루트와 동일합니다. /var/run/docker.sock에 접근할 수 있는 모든 것은 이 도구가 생성한 VM뿐만 아니라 머신의 모든 컨테이너를 제어할 수 있습니다. 신뢰하는 머신에서만 이 마운트로 이 이미지를 실행하고, MCP 서버 자체(또는 그 포트)를 신뢰할 수 없는 호출자에게 절대 노출하지 마세요.

• SSH 비밀번호는 평문으로 저장됩니다. docker-vm-mcp-state 볼륨(/data/credentials.json)에 저장되어 vm_ssh_info가 나중에 다시 반환할 수 있습니다. 개인 로컬 개발 도구에는 괜찮지만, 강화(예: 키 전용 인증으로 전환하고 비밀번호 저장 중단) 없이 다중 테넌트 또는 프로덕션 용도로 재사용하지 마세요.

• VM 컨테이너는 기본적으로 SSH 포트를 0.0.0.0(Docker 기본값)에 게시하므로 방화벽이 허용하면 로컬 네트워크의 다른 장치가 접근할 수 있습니다. 명시적 sshPort를 전달하고 방화벽을 설정하거나, 중요하다면 127.0.0.1에만 바인딩하세요(src/tools/createVm.ts의 PortBindings 호스트 IP를 127.0.0.1로 편집하고 다시 빌드).

실제 검증: ServiceNow Discovery

이 프로젝트는 실제 ServiceNow 인스턴스의 라이브 Discovery 대상으로 사용되었으며, 로컬에서 실행되는 MID Server(역시 Dockerized)를 통해 검증되었습니다. 이는 장난감이 아니라 실제 SSH로 접근 가능한 Linux 호스트처럼 동작한다는 증거입니다:

• 표준 Discovery, MID Server → Mac의 LAN IP와 VM의 게시된 SSH 포트(예: 192.168.x.x:<port>)를 통해 VM에 접속 — 호스트 이름, OS, RAM, CPU 세부 정보를 SSH로 실시간 가져와 cmdb_ci_linux_server CI를 성공적으로 생성했습니다.

• Quick Discovery도 동일하게 작동합니다.

• MID Server 컨테이너와 VM 컨테이너가 모두 Docker의 기본 bridge 네트워크에 있으므로, 게시된 포트 없이 내부 컨테이너 IP와 표준 SSH 포트(22)로 직접 서로 연결할 수도 있습니다. Mac의 LAN IP(네트워크에 따라 변경됨)에 의존하지 않습니다.

• 직접 시도할 때 알아두면 좋은 한 가지 특이점: 발견된 CPU 제조업체가 "Apple"로 표시됩니다. 이는 버그가 아니라 정확합니다. Mac용 Docker Desktop은 컨테이너를 호스트의 Apple Silicon 칩에서 직접 부팅된 linuxkit VM 내부에서 실행하므로, /proc/cpuinfo를 읽는 SSH 프로브는 다른 호스트에서와 마찬가지로 실제 하드웨어를 보게 됩니다.

프로젝트 구조

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

검증 방법에 대한 참고 사항

이 프로젝트는 npm 레지스트리에 접근할 수 없는 샌드박스 환경에서 빌드되고 타입 검사되었으므로, 여기서 npm install / npm run build를 종단 간 실행할 수 없었습니다. TypeScript는 Node 자체 타입 정의에 대해 오류 없이 검사되었습니다. 남은 검사는 @modelcontextprotocol/sdk, dockerode, zod의 자체 타입에 대한 것뿐이며, 해당 샌드박스에서는 설치할 수 없었습니다. 프로젝트를 Mac에 복사한 후 첫 docker build 전에 다음을 한 번 실행하세요:

npm install
npm run build

tsc가 위에서 이미 처리한 것 외에 무엇이든 보고하면, 대부분 @modelcontextprotocol/sdk의 버전별 API 변경(빠르게 움직이는 패키지)일 가능성이 높습니다. 해결책은 거의 항상 src/index.ts의 import 경로(@modelcontextprotocol/sdk/server/mcp.js / .../server/stdio.js)를 npm install이 해결한 버전에 맞게 약간 조정하는 것입니다.