Claude Code 가이드 - 한국 개발자를 위한 완벽한 가이드

도구 탐색

MCP 서버가 제공하는 도구(tools)와 리소스(resources)를 탐색하여 어떤 기능을 사용할 수 있는지 파악할 수 있습니다. 각 도구의 입력 파라미터, 반환 형식, 사용 예제를 확인하여 효과적으로 활용하세요.

bash

# MCP 도구 탐색 명령어

# 모든 도구 나열
claude mcp tools

# 특정 서버의 도구
claude mcp tools postgres

# 도구 상세 정보
claude mcp tool-info postgres:query

# 리소스 나열
claude mcp resources filesystem

bash

# 도구 목록 예시

$ claude mcp tools postgres

Available Tools:
┌───────────────┬──────────────────────────┬────────────────┐
│ Tool          │ Description              │ Parameters     │
├───────────────┼──────────────────────────┼────────────────┤
│ query         │ Execute SQL query        │ sql (required) │
│ list_tables   │ List all tables          │ schema         │
│ describe      │ Get table schema         │ table (req)    │
└───────────────┴──────────────────────────┴────────────────┘

자동 탐색 - 사용 가능한 모든 도구 확인
타입 정보 - 파라미터 타입과 제약사항
실시간 업데이트 - 서버 변경 시 자동 반영
문서 통합 - 도구 설명과 예제 제공

도구 사용하기

Claude에게 작업을 요청하면 적절한 MCP 도구를 자동으로 선택하고 실행합니다. 명시적으로 도구를 지정하거나, 자연어로 요청할 수 있습니다.

bash

# 자연어로 MCP 도구 사용

# PostgreSQL 쿼리
"데이터베이스에서 최근 10명의 사용자 조회해줘"
→ Claude가 postgres:query 도구 실행

# 파일 읽기
"프로젝트의 package.json 파일 내용 보여줘"
→ Claude가 filesystem:read_file 도구 실행

# GitHub 이슈 생성
"'버그 수정 필요' 제목으로 GitHub 이슈 만들어줘"
→ Claude가 github:create_issue 도구 실행

bash

# 명시적 도구 호출

# CLI에서 직접 호출
claude mcp call postgres:query \
  --args '{"sql": "SELECT * FROM users LIMIT 10"}'

# 결과 형식 지정
claude mcp call github:list_repos \
  --format json \
  --output repos.json

자동 선택 - 맥락에 맞는 도구 자동 실행
직접 호출 - CLI로 도구 명시적 실행
에러 처리 - 실패 시 자동 재시도
결과 변환 - 다양한 출력 형식 지원

리소스 접근

MCP 리소스는 파일, 데이터베이스 레코드, API 엔드포인트 등 읽기 가능한 데이터를 나타냅니다. Claude는 리소스 URI를 통해 다양한 소스의 정보에 접근할 수 있습니다.

bash

# 리소스 URI 형식

# 파일 시스템
file:///Users/username/project/README.md

# 데이터베이스
postgres://localhost/mydb/users/123

# GitHub
github://owner/repo/issues/45

# 리소스 읽기
claude mcp resource read file:///path/to/file.txt

bash

# 리소스 활용 예제

# 1. 여러 파일 동시 읽기
"README.md와 package.json 내용을 비교해줘"

# 2. 데이터베이스 레코드 조회
"사용자 ID 123의 주문 내역 보여줘"

# 3. GitHub 이슈 분석
"이번 주에 생성된 모든 버그 이슈 요약해줘"

URI 기반 - 표준 리소스 식별자
캐싱 - 자주 사용하는 리소스 캐시
스트리밍 - 대용량 데이터 스트리밍 지원
권한 관리 - 리소스별 접근 제어

프롬프트 템플릿

MCP 서버는 재사용 가능한 프롬프트 템플릿을 제공할 수 있습니다. 자주 사용하는 작업을 템플릿으로 저장하여 일관된 결과를 얻을 수 있습니다.

bash

# 프롬프트 템플릿 사용

# 사용 가능한 템플릿 나열
claude mcp prompts postgres

# 템플릿 실행
claude mcp prompt postgres:analyze-schema \
  --args table=users

# 커스텀 템플릿 등록
claude mcp prompt register my-template \
  --file templates/my-template.txt

text

# 템플릿 예시: 데이터베이스 분석

이 테이블을 분석해주세요:

테이블: {{table_name}}
스키마:
{{schema}}

다음을 포함하여 분석해주세요:
1. 데이터 타입 적절성
2. 인덱스 최적화 기회
3. 정규화 수준
4. 성능 개선 제안

재사용성 - 공통 작업 템플릿화
변수 치환 - 동적 값 주입
버전 관리 - 템플릿 변경 이력
팀 공유 - 조직 전체 활용

도구 조합

여러 MCP 도구를 조합하여 복잡한 워크플로우를 자동화할 수 있습니다. 한 도구의 출력을 다른 도구의 입력으로 사용하여 체인을 구성합니다.

bash

# 도구 체이닝 예제

# 1. DB 조회 → 파일 저장 → GitHub 이슈
"데이터베이스에서 미처리 주문을 조회하고,
CSV로 저장한 뒤 GitHub 이슈로 등록해줘"

# 실행 순서:
# 1. postgres:query (미처리 주문 조회)
# 2. filesystem:write_file (CSV 저장)
# 3. github:create_issue (이슈 생성, CSV 첨부)

# 2. 파일 읽기 → 분석 → Slack 전송
"로그 파일의 에러를 분석해서 Slack에 보고해줘"

# 실행 순서:
# 1. filesystem:read_file (로그 읽기)
# 2. 에러 패턴 분석
# 3. slack:post_message (결과 전송)

yaml

# 스크립트로 워크플로우 정의

# workflow.yaml
name: daily-report
steps:
  - tool: postgres:query
    args:
      sql: "SELECT * FROM sales WHERE date = CURRENT_DATE"
    output: sales_data

  - tool: analyze
    input: sales_data
    output: analysis

  - tool: slack:post
    args:
      channel: "#reports"
      message: "{{analysis}}"

# 실행
claude mcp workflow run daily-report

자동 체이닝 - 도구 간 데이터 흐름
조건부 실행 - 결과에 따른 분기
병렬 실행 - 독립적 작업 동시 수행
에러 복구 - 실패 시 자동 재시도

활용 사례

MCP를 활용한 실제 사용 사례를 통해 효과적인 통합 방법을 학습하세요. 데이터베이스 관리부터 CI/CD 자동화까지 다양한 시나리오를 다룹니다.

bash

# 사례 1: 데이터베이스 마이그레이션 검증

"production과 staging DB 스키마를 비교해서
차이점을 GitHub 이슈로 만들어줘"

사용 도구:
- postgres:describe (production)
- postgres:describe (staging)
- 스키마 비교 분석
- github:create_issue

# 사례 2: 자동화된 코드 리뷰

"PR #123의 변경된 파일을 읽고,
데이터베이스 쿼리가 있으면 성능 분석한 뒤
리뷰 코멘트 남겨줘"

사용 도구:
- github:get_pr_files
- filesystem:read_file
- postgres:explain (쿼리 분석)
- github:create_review_comment

bash

# 사례 3: 일일 보고서 자동화

# 매일 오전 9시 실행
0 9 * * * claude mcp workflow run daily-report

# daily-report workflow:
1. PostgreSQL에서 어제 판매 데이터 조회
2. 차트 이미지 생성 (filesystem 저장)
3. Slack에 보고서 전송
4. GitHub Wiki에 기록

# 사례 4: 장애 대응 자동화

"로그 파일에서 ERROR 패턴 찾아서,
관련 데이터베이스 레코드 조회하고,
원인 분석 후 Slack 알림 보내줘"

사용 도구:
- filesystem:search
- postgres:query
- 로그 분석 + 원인 추론
- slack:post_urgent

DB 관리 - 스키마 비교, 마이그레이션
CI/CD 자동화 - 배포, 테스트, 리뷰
모니터링 - 로그 분석, 알림
보고서 - 데이터 집계, 시각화

실전 팁: 작은 작업부터 시작하여 점진적으로 복잡한 워크플로우를 구축하세요. 각 단계를 테스트하면서 안정성을 확보하는 것이 중요합니다.

다음 단계

MCP 도구 사용를 익혔습니다. 다음 주제로 넘어가보세요.

도구 탐색

bash

# MCP 도구 탐색 명령어

# 모든 도구 나열
claude mcp tools

# 특정 서버의 도구
claude mcp tools postgres

# 도구 상세 정보
claude mcp tool-info postgres:query

# 리소스 나열
claude mcp resources filesystem

bash

# 도구 목록 예시

$ claude mcp tools postgres

Available Tools:
┌───────────────┬──────────────────────────┬────────────────┐
│ Tool          │ Description              │ Parameters     │
├───────────────┼──────────────────────────┼────────────────┤
│ query         │ Execute SQL query        │ sql (required) │
│ list_tables   │ List all tables          │ schema         │
│ describe      │ Get table schema         │ table (req)    │
└───────────────┴──────────────────────────┴────────────────┘

자동 탐색 - 사용 가능한 모든 도구 확인
타입 정보 - 파라미터 타입과 제약사항
실시간 업데이트 - 서버 변경 시 자동 반영
문서 통합 - 도구 설명과 예제 제공

도구 사용하기

Claude에게 작업을 요청하면 적절한 MCP 도구를 자동으로 선택하고 실행합니다. 명시적으로 도구를 지정하거나, 자연어로 요청할 수 있습니다.

bash

# 자연어로 MCP 도구 사용

# PostgreSQL 쿼리
"데이터베이스에서 최근 10명의 사용자 조회해줘"
→ Claude가 postgres:query 도구 실행

# 파일 읽기
"프로젝트의 package.json 파일 내용 보여줘"
→ Claude가 filesystem:read_file 도구 실행

# GitHub 이슈 생성
"'버그 수정 필요' 제목으로 GitHub 이슈 만들어줘"
→ Claude가 github:create_issue 도구 실행

bash

# 명시적 도구 호출

# CLI에서 직접 호출
claude mcp call postgres:query \
  --args '{"sql": "SELECT * FROM users LIMIT 10"}'

# 결과 형식 지정
claude mcp call github:list_repos \
  --format json \
  --output repos.json

자동 선택 - 맥락에 맞는 도구 자동 실행
직접 호출 - CLI로 도구 명시적 실행
에러 처리 - 실패 시 자동 재시도
결과 변환 - 다양한 출력 형식 지원

리소스 접근

bash

# 리소스 URI 형식

# 파일 시스템
file:///Users/username/project/README.md

# 데이터베이스
postgres://localhost/mydb/users/123

# GitHub
github://owner/repo/issues/45

# 리소스 읽기
claude mcp resource read file:///path/to/file.txt

bash

# 리소스 활용 예제

# 1. 여러 파일 동시 읽기
"README.md와 package.json 내용을 비교해줘"

# 2. 데이터베이스 레코드 조회
"사용자 ID 123의 주문 내역 보여줘"

# 3. GitHub 이슈 분석
"이번 주에 생성된 모든 버그 이슈 요약해줘"

URI 기반 - 표준 리소스 식별자
캐싱 - 자주 사용하는 리소스 캐시
스트리밍 - 대용량 데이터 스트리밍 지원
권한 관리 - 리소스별 접근 제어

프롬프트 템플릿

MCP 서버는 재사용 가능한 프롬프트 템플릿을 제공할 수 있습니다. 자주 사용하는 작업을 템플릿으로 저장하여 일관된 결과를 얻을 수 있습니다.

bash

# 프롬프트 템플릿 사용

# 사용 가능한 템플릿 나열
claude mcp prompts postgres

# 템플릿 실행
claude mcp prompt postgres:analyze-schema \
  --args table=users

# 커스텀 템플릿 등록
claude mcp prompt register my-template \
  --file templates/my-template.txt

text

# 템플릿 예시: 데이터베이스 분석

이 테이블을 분석해주세요:

테이블: {{table_name}}
스키마:
{{schema}}

다음을 포함하여 분석해주세요:
1. 데이터 타입 적절성
2. 인덱스 최적화 기회
3. 정규화 수준
4. 성능 개선 제안

재사용성 - 공통 작업 템플릿화
변수 치환 - 동적 값 주입
버전 관리 - 템플릿 변경 이력
팀 공유 - 조직 전체 활용

도구 조합

여러 MCP 도구를 조합하여 복잡한 워크플로우를 자동화할 수 있습니다. 한 도구의 출력을 다른 도구의 입력으로 사용하여 체인을 구성합니다.

bash

# 도구 체이닝 예제

# 1. DB 조회 → 파일 저장 → GitHub 이슈
"데이터베이스에서 미처리 주문을 조회하고,
CSV로 저장한 뒤 GitHub 이슈로 등록해줘"

# 실행 순서:
# 1. postgres:query (미처리 주문 조회)
# 2. filesystem:write_file (CSV 저장)
# 3. github:create_issue (이슈 생성, CSV 첨부)

# 2. 파일 읽기 → 분석 → Slack 전송
"로그 파일의 에러를 분석해서 Slack에 보고해줘"

# 실행 순서:
# 1. filesystem:read_file (로그 읽기)
# 2. 에러 패턴 분석
# 3. slack:post_message (결과 전송)

yaml

# 스크립트로 워크플로우 정의

# workflow.yaml
name: daily-report
steps:
  - tool: postgres:query
    args:
      sql: "SELECT * FROM sales WHERE date = CURRENT_DATE"
    output: sales_data

  - tool: analyze
    input: sales_data
    output: analysis

  - tool: slack:post
    args:
      channel: "#reports"
      message: "{{analysis}}"

# 실행
claude mcp workflow run daily-report

자동 체이닝 - 도구 간 데이터 흐름
조건부 실행 - 결과에 따른 분기
병렬 실행 - 독립적 작업 동시 수행
에러 복구 - 실패 시 자동 재시도

활용 사례

MCP를 활용한 실제 사용 사례를 통해 효과적인 통합 방법을 학습하세요. 데이터베이스 관리부터 CI/CD 자동화까지 다양한 시나리오를 다룹니다.

bash

# 사례 1: 데이터베이스 마이그레이션 검증

"production과 staging DB 스키마를 비교해서
차이점을 GitHub 이슈로 만들어줘"

사용 도구:
- postgres:describe (production)
- postgres:describe (staging)
- 스키마 비교 분석
- github:create_issue

# 사례 2: 자동화된 코드 리뷰

"PR #123의 변경된 파일을 읽고,
데이터베이스 쿼리가 있으면 성능 분석한 뒤
리뷰 코멘트 남겨줘"

사용 도구:
- github:get_pr_files
- filesystem:read_file
- postgres:explain (쿼리 분석)
- github:create_review_comment

bash

# 사례 3: 일일 보고서 자동화

# 매일 오전 9시 실행
0 9 * * * claude mcp workflow run daily-report

# daily-report workflow:
1. PostgreSQL에서 어제 판매 데이터 조회
2. 차트 이미지 생성 (filesystem 저장)
3. Slack에 보고서 전송
4. GitHub Wiki에 기록

# 사례 4: 장애 대응 자동화

"로그 파일에서 ERROR 패턴 찾아서,
관련 데이터베이스 레코드 조회하고,
원인 분석 후 Slack 알림 보내줘"

사용 도구:
- filesystem:search
- postgres:query
- 로그 분석 + 원인 추론
- slack:post_urgent

DB 관리 - 스키마 비교, 마이그레이션
CI/CD 자동화 - 배포, 테스트, 리뷰
모니터링 - 로그 분석, 알림
보고서 - 데이터 집계, 시각화

실전 팁: 작은 작업부터 시작하여 점진적으로 복잡한 워크플로우를 구축하세요. 각 단계를 테스트하면서 안정성을 확보하는 것이 중요합니다.

다음 단계

MCP 도구 사용를 익혔습니다. 다음 주제로 넘어가보세요.

MCP 도구 사용

도구 탐색

도구 사용하기

리소스 접근

프롬프트 템플릿

도구 조합

활용 사례

다음 단계

로딩 중...

MCP 도구 사용

도구 탐색

도구 사용하기

리소스 접근

프롬프트 템플릿

도구 조합

활용 사례

다음 단계