Claude Code와 Docker MCP Toolkit으로 Docker Compose 파일 생성하기

Claude Code를 Docker MCP Toolkit에 연결해 Docker Hub 이미지를 검색하고 자연어로 완전한 Docker Compose 스택을 생성하는 방법을 보여주는 가이드예요.

출처: 문서

본문

이 가이드는 Claude가 Docker Hub를 실시간으로 검색하고 자연어로 완전한 docker-compose.yaml 을 생성할 수 있도록 Claude Code를 Docker MCP Toolkit과 함께 사용하는 방법을 소개해요.

YAML을 수동으로 작성하거나 이미지 태그를 찾는 대신, 스택을 한 번만 설명하면 돼요. Claude가 Model Context Protocol(MCP)을 사용해 Docker Hub를 쿼리하고 프로덕션 준비가 된 Compose 파일을 만들어줘요.

이 가이드에서 배울 내용:

Docker Desktop에서 Docker MCP Toolkit 활성화하기
Docker Hub MCP 서버 추가하기
Claude Code를 MCP Gateway에 연결하기(GUI 또는 CLI)
Claude 내부에서 MCP 연결 확인하기
Claude에게 Node.js + PostgreSQL 앱용 Compose 파일을 생성하고 저장하라고 요청하기
docker compose up 으로 즉시 배포하기

Claude Code와 Docker MCP Toolkit을 사용해 자연어로 Docker Compose 파일을 생성하는 과정:

Setup(설정): MCP Toolkit 활성화 → Docker Hub MCP 서버 추가 → Claude Code 연결
Use Claude(사용): 스택을 평이한 영어로 설명하기
Automate(자동화): Claude가 MCP로 Docker Hub를 쿼리하고 완전한 docker-compose.yaml 을 만듦
Deploy(배포): docker compose up 실행 → Node.js + PostgreSQL이 localhost:3000 에서 실행됨
Benefit(이점): YAML 작성 0회. 이미지 검색 0회. 한 번 설명하면 Claude가 만들어줌.

예상 시간: 약 15분

1. 무엇을 만들까요

목표는 간단해요. Claude Code를 Docker MCP Toolkit과 함께 사용해 Docker Hub 이미지를 검색하고 Node.js와 PostgreSQL 설정을 위한 완전한 Docker Compose 파일을 생성하는 거예요.

Model Context Protocol(MCP)은 Claude Code와 Docker Desktop을 연결해 Claude에 Docker 도구에 대한 실시간 접근을 제공해요. Docker, 터미널 명령, YAML 편집기 사이를 오가는 대신 요구사항을 한 번 설명하면 Claude가 인프라 세부사항을 처리해요.

왜 중요한가요: 이 패턴은 대화형 프롬프트만으로 복잡한 멀티 서비스 설정, 데이터베이스 마이그레이션, 네트워킹, 보안 정책까지 확장할 수 있어요.

2. 사전 요구사항

다음이 갖춰져 있는지 확인해주세요:

Docker Desktop 설치
MCP Toolkit 지원으로 업데이트된 Docker Desktop
Claude Code 설치

3. Docker Hub MCP 서버 설치하기

Docker Desktop을 열고 MCP Toolkit 을 선택한 후 Catalog 탭으로 이동해주세요. Docker Hub 를 검색하고 Docker Hub MCP 서버를 선택해주세요. MCP 서버를 추가한 뒤 Configuration 탭을 열어 Docker Hub 사용자 이름을 입력하고, 읽기 전용 개인 액세스 토큰 을 만들어 Secrets 아래에 액세스 토큰을 입력하고, 구성을 저장해주세요.

참고: Docker Hub 공개 이미지는 자격 증명 없이 작동해요. 프라이빗 리포지토리의 경우 나중에 Docker Hub 사용자 이름과 토큰을 추가할 수 있어요.

4. Claude Code를 Docker MCP Toolkit에 연결하기

Docker Desktop에서 또는 CLI를 사용해 연결할 수 있어요.

방법 A. Docker Desktop으로 연결

MCP Toolkit 을 열고 Clients 탭으로 가서 Claude Code 를 찾은 뒤 Connect 를 선택해주세요.

방법 B. CLI로 연결

$ claude mcp add MCP_DOCKER -s user -- docker mcp gateway run

5. Claude Code 내부에서 MCP 서버 확인하기

프로젝트 폴더로 이동해주세요:

$ cd /path/to/project

Claude Code를 시작해주세요:

$ claude

입력 상자에 다음을 입력해주세요:

/mcp

이제 다음이 보여야 해요:

MCP 게이트웨이(예: MCP_DOCKER )
Docker Hub MCP 서버가 제공하는 도구

그렇지 않다면 Claude Code를 재시작하거나 Docker Desktop에서 연결을 확인해주세요.

6. 기본 Node.js 앱 만들기

Claude Code는 실제 프로젝트를 검사할 수 있을 때 더 정확한 Compose 파일을 생성해요. 나중에 에이전트가 바인드 마운트할 수 있도록 지금 어플리케이션 코드를 설정해주세요.

프로젝트 폴더 안에 app 이라는 폴더를 만들어주세요:

$ mkdir app
$ cd app
$ npm init -y
$ npm install express

index.js 를 만들어주세요:

const express = require("express");
const app = express();

app.get("/", (req, res) => {
  res.send("Node.js, Docker, and MCP Toolkit are working together!");
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

package.json 에 시작 스크립트를 추가해주세요:

"scripts": {
  "start": "node index.js"
}

앱이 준비되면 프로젝트 루트로 돌아가세요( cd .. ).

7. Claude Code에게 Docker Compose 스택 설계 요청하기

Claude Code에 다음 메시지를 붙여넣어주세요:

Using the Docker Hub MCP server:
Search Docker Hub for an official Node.js image and a PostgreSQL image.
Choose stable, commonly used tags such as the Node LTS version and a recent major Postgres version.
Generate a Docker Compose file (`docker-compose.yaml`) with:
- app:
  - runs on port 3000
  - bind mounts the existing ./app directory into /usr/src/app
  - sets /usr/src/app as the working directory and runs `npm install && npm start`
- db: running on port 5432 using a named volume
Include:
- Environment variables for Postgres
- A shared bridge network
- Healthchecks where appropriate
- Pin the image version using the tag + index digest

Claude가 MCP로 이미지를 검색하고, app 디렉터리를 검사하며, 내 로컬 코드를 마운트·실행하는 Compose 파일을 생성할 거예요.

8. 생성된 Docker Compose 파일 저장하기

Claude에게 말해주세요:

Save the final Docker Compose file (docker-compose.yaml) into the current project directory.

다음처럼 생긴 결과가 보여야 해요:

services:
  app:
    image: node:<tag>
    working_dir: /usr/src/app
    volumes:
      - .:/usr/src/app
    ports:
      - "3000:3000"
    depends_on:
      - db
    networks:
      - app-net
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: example
      POSTGRES_PASSWORD: example
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql
    ports:
      - "5432:5432"
    networks:
      - app-net
volumes:
  db-data:
networks:
  app-net:
    driver: bridge

9. Docker Compose 스택 실행하기

프로젝트 루트에서:

$ docker compose up

Docker가:

Docker Hub MCP로 선택된 Node 및 Postgres 이미지를 내려받음
네트워크와 볼륨을 생성함
컨테이너를 시작함

브라우저를 여세요:

http://localhost:3000

이제 내 Node.js 앱이 실행 중이어야 해요.

결론

Claude Code를 Docker MCP Toolkit, Docker Desktop, Docker Hub MCP 서버와 결합하면 스택을 자연어로 설명하고 세부사항은 MCP가 처리하게 할 수 있어요. 이는 컨텍스트 전환을 제거하고 모델 컨텍스트 프로토콜 통합으로 구동되는 부드럽고 안내되는 워크플로로 대체해요.

다음 단계

Docker MCP 카탈로그 에서 사용 가능한 220+ MCP 서버 탐구하기
Claude Code를 내 데이터베이스, 내부 API, 팀 도구에 연결하기
MCP 설정을 팀과 공유해 모두가 일관되게 작업하기

개발의 미래는 도구 간 전환이 아니라 도구들이 간단하고 안전하며 예측 가능한 방식으로 함께 작동하는 것이에요. Docker MCP Toolkit은 그 미래를 일상 워크플로로 가져와요.

더 알아보기

MCP 카탈로그 탐구 : 컨테이너화되고 보안 강화된 MCP 서버 발견하기
Docker Desktop에서 MCP Toolkit 시작하기 : 자동 실행에는 버전 4.48 이상 필요
MCP Horror Stories 시리즈 읽기 : 흔한 MCP 보안 함정과 이를 피하는 방법 배우기

더 알아보기 (Learn more)

Docker MCP Toolkit
Model Context Protocol(MCP)
Claude Code