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

MCP 서버 설치

MCP (Model Context Protocol) 서버는 Claude Code가 외부 시스템과 통합하는 핵심 메커니즘입니다. 데이터베이스, API, 파일 시스템, 클라우드 서비스 등 다양한 리소스에 접근할 수 있게 해줍니다. MCP 서버는 npm 패키지, Python 패키지, 또는 독립 실행 파일로 제공되며, Claude Code 설정 파일에 등록하여 사용합니다. 공식 MCP 서버 디렉토리에서 검증된 서버를 찾거나, 커뮤니티가 제작한 서버를 설치할 수 있습니다.

bash

# MCP 서버 검색
claude mcp list

# 인기 MCP 서버 목록
Name              Description                   Provider
────────────────  ───────────────────────────   ─────────
@modelcontextprotocol/server-postgres   PostgreSQL 연결       Official
@modelcontextprotocol/server-filesystem 파일 시스템 접근      Official
@modelcontextprotocol/server-github     GitHub API 통합       Official
@modelcontextprotocol/server-slack      Slack 통합            Official
mcp-server-sqlite SQLite 데이터베이스      Community
mcp-server-aws    AWS 서비스 통합           Community

bash

# npm 패키지로 제공되는 MCP 서버 설치

# 1. PostgreSQL MCP 서버
npm install -g @modelcontextprotocol/server-postgres

# 2. 파일 시스템 MCP 서버
npm install -g @modelcontextprotocol/server-filesystem

# 3. GitHub MCP 서버
npm install -g @modelcontextprotocol/server-github

# 설치 확인
claude mcp installed

bash

# Python MCP 서버 설치

# 1. Python 가상환경 생성 (권장)
python -m venv ~/.mcp-servers/venv
source ~/.mcp-servers/venv/bin/activate

# 2. MCP 서버 설치
pip install mcp-server-sqlite
pip install mcp-server-mongodb

# 3. Claude Code에 등록
claude mcp add sqlite \
  --command "~/.mcp-servers/venv/bin/mcp-server-sqlite" \
  --args "path/to/database.db"

bash

# 커스텀 MCP 서버 로컬 설치

# Git 저장소에서 설치
git clone https://github.com/user/custom-mcp-server.git
cd custom-mcp-server
npm install
npm run build

# Claude Code에 등록
claude mcp add custom-server \
  --command "node" \
  --args "/path/to/custom-mcp-server/dist/index.js" \
  --env "API_KEY=your_key_here"

공식 서버 - Anthropic 검증 MCP 서버
커뮤니티 서버 - 다양한 서비스 통합
간편한 설치 - npm/pip로 원클릭 설치
버전 관리 - 자동 업데이트 및 롤백

설치 위치: 글로벌 설치(-g)를 권장하지만, 프로젝트별로 다른 버전이 필요하면 로컬 설치 후 경로를 명시하세요.

공식 서버 우선: 가능하면 @modelcontextprotocol 네임스페이스의 공식 서버를 사용하세요. 보안과 안정성이 검증되어 있습니다.

설정 파일 구성

MCP 서버 설정은 Claude Code의 설정 파일에서 관리됩니다. 각 서버의 실행 명령어, 인자, 환경 변수를 JSON 형식으로 정의합니다. 글로벌 설정과 프로젝트별 설정을 분리하여 관리할 수 있으며, 팀 전체가 동일한 MCP 설정을 공유하도록 Git에 커밋할 수도 있습니다. 설정 파일은 자동완성과 스키마 검증을 지원하여 오류를 사전에 방지합니다.

bash

# 설정 파일 위치

# 글로벌 설정 (모든 프로젝트에 적용)
~/.claude/mcp-servers.json

# 프로젝트별 설정 (현재 프로젝트만)
.claude/mcp-servers.json

# 우선순위: 프로젝트 > 글로벌

json

// ~/.claude/mcp-servers.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ],
      "env": {
        "PGUSER": "admin",
        "PGPASSWORD": "${POSTGRES_PASSWORD}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_PERSONAL_TOKEN}"
      }
    }
  }
}

bash

# MCP 설정 파일 관리 명령어

# 설정 파일 생성
claude mcp init

# 설정 파일 위치 확인
claude mcp config --location

# 설정 검증
claude mcp config --validate

# 특정 서버 설정 보기
claude mcp config get postgres

# 서버 추가 (대화형)
claude mcp add

# 서버 제거
claude mcp remove github

# 설정 파일 편집
claude mcp config --edit

json

// 프로젝트별 설정 예제
// .claude/mcp-servers.json

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/project_db"
      ],
      "env": {
        "PGDATABASE": "project_db"
      },
      "disabled": false  // 일시적으로 비활성화
    },
    "local-files": {
      "command": "node",
      "args": [
        "/absolute/path/to/custom-mcp-server.js"
      ],
      "cwd": "/path/to/working/directory",
      "timeout": 30000  // 30초 타임아웃
    }
  }
}

JSON 스키마 - 자동완성 및 검증 지원
환경 변수 - ${VAR} 문법으로 주입
글로벌/로컬 - 용도에 맞게 설정 분리
Git 공유 - 팀 전체가 동일 설정 사용

환경 변수 활용: 민감한 정보(API 키, 비밀번호)는 설정 파일에 직접 입력하지 말고 환경 변수로 주입하세요.

절대 경로 사용: command와 args에는 절대 경로를 사용하는 것이 안전합니다. 상대 경로는 실행 위치에 따라 다르게 해석될 수 있습니다.

인증 설정

대부분의 MCP 서버는 외부 서비스와 통신하기 위해 인증이 필요합니다. API 키, OAuth 토큰, 데이터베이스 비밀번호 등을 안전하게 관리하는 것이 중요합니다. Claude Code는 환경 변수를 통한 인증 정보 주입을 지원하며, 시스템 키체인과의 통합도 제공합니다. 인증 정보는 절대 Git에 커밋하지 않도록 주의해야 합니다.

bash

# 환경 변수로 인증 정보 설정

# .env 파일 생성 (.gitignore에 추가 필수!)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
POSTGRES_PASSWORD=super_secret_password
SLACK_API_KEY=xoxb-xxxxxxxxxxxx
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Claude Code 실행 시 환경 변수 로드
claude --env-file .env

json

// MCP 설정에서 환경 변수 사용
// .claude/mcp-servers.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "aws": {
      "command": "mcp-server-aws",
      "env": {
        "AWS_ACCESS_KEY_ID": "${AWS_ACCESS_KEY_ID}",
        "AWS_SECRET_ACCESS_KEY": "${AWS_SECRET_ACCESS_KEY}",
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

bash

# 시스템 키체인 사용 (macOS/Linux)

# 키체인에 비밀번호 저장
security add-generic-password \
  -s "claude-mcp-postgres" \
  -a "dbuser" \
  -w "secret_password"

# 키체인에서 읽어오기
export POSTGRES_PASSWORD=$(security find-generic-password \
  -s "claude-mcp-postgres" -w)

# Claude Code 실행
claude

환경 변수 - .env 파일로 관리
키체인 통합 - OS 보안 저장소 활용
OAuth 지원 - 자동 토큰 갱신
안전한 저장 - 암호화된 저장소

보안 주의: .env 파일을 .gitignore에 반드시 추가하세요. 인증 정보가 Git에 커밋되면 공개 저장소에서 즉시 악용될 수 있습니다.

연결 테스트

MCP 서버 설정 후에는 연결이 정상적으로 작동하는지 테스트해야 합니다. Claude Code는 연결 상태를 확인하고, 사용 가능한 도구와 리소스를 나열하며, 간단한 테스트 쿼리를 실행하는 기능을 제공합니다.

bash

# MCP 서버 연결 테스트

# 모든 서버 상태 확인
claude mcp status

# 특정 서버 테스트
claude mcp test postgres

# 상세 진단
claude mcp diagnose github --verbose

# 사용 가능한 도구 나열
claude mcp tools postgres

bash

# 테스트 결과 예시

$ claude mcp status

MCP Servers Status:
┌──────────────┬──────────┬─────────────────────┐
│ Name         │ Status   │ Uptime              │
├──────────────┼──────────┼─────────────────────┤
│ postgres     │ ✓ Active │ 2h 34m              │
│ filesystem   │ ✓ Active │ 2h 34m              │
│ github       │ ✗ Error  │ Connection refused  │
│ slack        │ ⊘ Off    │ Disabled            │
└──────────────┴──────────┴─────────────────────┘

상태 모니터링 - 실시간 연결 상태
도구 탐색 - 사용 가능한 기능 확인
진단 도구 - 문제 원인 파악
자동 재연결 - 연결 실패 시 재시도

다중 서버 관리

여러 MCP 서버를 동시에 사용하면 다양한 리소스에 접근할 수 있습니다. 데이터베이스, 파일 시스템, API를 통합하여 복잡한 작업을 자동화할 수 있습니다. 각 서버는 독립적으로 실행되며, 필요에 따라 활성화/비활성화할 수 있습니다.

json

// 다중 MCP 서버 설정 예시
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/db"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "disabled": true  // 필요할 때만 활성화
    }
  }
}

bash

# 서버 관리 명령어

# 특정 서버 활성화/비활성화
claude mcp enable slack
claude mcp disable github

# 서버 재시작
claude mcp restart postgres

# 모든 서버 재시작
claude mcp restart --all

# 서버 로그 보기
claude mcp logs postgres --tail 50

동시 실행 - 여러 서버 병렬 사용
독립적 관리 - 개별 제어 가능
리소스 최적화 - 필요한 서버만 실행
통합 쿼리 - 여러 소스 동시 접근

MCP 문제 해결

MCP 서버 연결 문제는 대부분 설정 오류나 네트워크 문제에서 발생합니다. Claude Code는 자동 진단 도구를 제공하여 문제를 빠르게 식별하고 해결할 수 있습니다.

bash

# 일반적인 문제와 해결 방법

# 문제 1: 서버가 시작되지 않음
$ claude mcp diagnose postgres

원인: command 경로가 잘못됨
해결: which npx로 정확한 경로 확인

# 문제 2: 인증 실패
원인: 환경 변수가 로드되지 않음
해결: .env 파일 경로 확인, claude --env-file .env 사용

# 문제 3: 타임아웃 발생
원인: 서버 응답 시간 초과
해결: timeout 값 증가 (설정 파일에 "timeout": 60000)

bash

# 디버그 모드 실행

# 상세 로그 출력
claude --debug mcp status

# 특정 서버 디버그
CLAUDE_LOG_LEVEL=debug claude mcp test github

# 로그 파일 위치
~/.claude/logs/mcp-postgres.log
~/.claude/logs/mcp-github.log

로그 확인: 문제 발생 시 가장 먼저 로그를 확인하세요. 대부분의 오류 원인이 로그에 명확히 표시됩니다.

포트 충돌: 일부 MCP 서버는 특정 포트를 사용합니다. 다른 프로세스가 해당 포트를 사용 중이면 연결에 실패할 수 있습니다.

다음 단계

MCP 서버 설정를 익혔습니다. 다음 주제로 넘어가보세요.

MCP 서버 설치

bash

# MCP 서버 검색
claude mcp list

# 인기 MCP 서버 목록
Name              Description                   Provider
────────────────  ───────────────────────────   ─────────
@modelcontextprotocol/server-postgres   PostgreSQL 연결       Official
@modelcontextprotocol/server-filesystem 파일 시스템 접근      Official
@modelcontextprotocol/server-github     GitHub API 통합       Official
@modelcontextprotocol/server-slack      Slack 통합            Official
mcp-server-sqlite SQLite 데이터베이스      Community
mcp-server-aws    AWS 서비스 통합           Community

bash

# npm 패키지로 제공되는 MCP 서버 설치

# 1. PostgreSQL MCP 서버
npm install -g @modelcontextprotocol/server-postgres

# 2. 파일 시스템 MCP 서버
npm install -g @modelcontextprotocol/server-filesystem

# 3. GitHub MCP 서버
npm install -g @modelcontextprotocol/server-github

# 설치 확인
claude mcp installed

bash

# Python MCP 서버 설치

# 1. Python 가상환경 생성 (권장)
python -m venv ~/.mcp-servers/venv
source ~/.mcp-servers/venv/bin/activate

# 2. MCP 서버 설치
pip install mcp-server-sqlite
pip install mcp-server-mongodb

# 3. Claude Code에 등록
claude mcp add sqlite \
  --command "~/.mcp-servers/venv/bin/mcp-server-sqlite" \
  --args "path/to/database.db"

bash

# 커스텀 MCP 서버 로컬 설치

# Git 저장소에서 설치
git clone https://github.com/user/custom-mcp-server.git
cd custom-mcp-server
npm install
npm run build

# Claude Code에 등록
claude mcp add custom-server \
  --command "node" \
  --args "/path/to/custom-mcp-server/dist/index.js" \
  --env "API_KEY=your_key_here"

공식 서버 - Anthropic 검증 MCP 서버
커뮤니티 서버 - 다양한 서비스 통합
간편한 설치 - npm/pip로 원클릭 설치
버전 관리 - 자동 업데이트 및 롤백

설치 위치: 글로벌 설치(-g)를 권장하지만, 프로젝트별로 다른 버전이 필요하면 로컬 설치 후 경로를 명시하세요.

공식 서버 우선: 가능하면 @modelcontextprotocol 네임스페이스의 공식 서버를 사용하세요. 보안과 안정성이 검증되어 있습니다.

설정 파일 구성

bash

# 설정 파일 위치

# 글로벌 설정 (모든 프로젝트에 적용)
~/.claude/mcp-servers.json

# 프로젝트별 설정 (현재 프로젝트만)
.claude/mcp-servers.json

# 우선순위: 프로젝트 > 글로벌

json

// ~/.claude/mcp-servers.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ],
      "env": {
        "PGUSER": "admin",
        "PGPASSWORD": "${POSTGRES_PASSWORD}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_PERSONAL_TOKEN}"
      }
    }
  }
}

bash

# MCP 설정 파일 관리 명령어

# 설정 파일 생성
claude mcp init

# 설정 파일 위치 확인
claude mcp config --location

# 설정 검증
claude mcp config --validate

# 특정 서버 설정 보기
claude mcp config get postgres

# 서버 추가 (대화형)
claude mcp add

# 서버 제거
claude mcp remove github

# 설정 파일 편집
claude mcp config --edit

json

// 프로젝트별 설정 예제
// .claude/mcp-servers.json

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/project_db"
      ],
      "env": {
        "PGDATABASE": "project_db"
      },
      "disabled": false  // 일시적으로 비활성화
    },
    "local-files": {
      "command": "node",
      "args": [
        "/absolute/path/to/custom-mcp-server.js"
      ],
      "cwd": "/path/to/working/directory",
      "timeout": 30000  // 30초 타임아웃
    }
  }
}

JSON 스키마 - 자동완성 및 검증 지원
환경 변수 - ${VAR} 문법으로 주입
글로벌/로컬 - 용도에 맞게 설정 분리
Git 공유 - 팀 전체가 동일 설정 사용

환경 변수 활용: 민감한 정보(API 키, 비밀번호)는 설정 파일에 직접 입력하지 말고 환경 변수로 주입하세요.

절대 경로 사용: command와 args에는 절대 경로를 사용하는 것이 안전합니다. 상대 경로는 실행 위치에 따라 다르게 해석될 수 있습니다.

인증 설정

bash

# 환경 변수로 인증 정보 설정

# .env 파일 생성 (.gitignore에 추가 필수!)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
POSTGRES_PASSWORD=super_secret_password
SLACK_API_KEY=xoxb-xxxxxxxxxxxx
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Claude Code 실행 시 환경 변수 로드
claude --env-file .env

json

// MCP 설정에서 환경 변수 사용
// .claude/mcp-servers.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "aws": {
      "command": "mcp-server-aws",
      "env": {
        "AWS_ACCESS_KEY_ID": "${AWS_ACCESS_KEY_ID}",
        "AWS_SECRET_ACCESS_KEY": "${AWS_SECRET_ACCESS_KEY}",
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

bash

# 시스템 키체인 사용 (macOS/Linux)

# 키체인에 비밀번호 저장
security add-generic-password \
  -s "claude-mcp-postgres" \
  -a "dbuser" \
  -w "secret_password"

# 키체인에서 읽어오기
export POSTGRES_PASSWORD=$(security find-generic-password \
  -s "claude-mcp-postgres" -w)

# Claude Code 실행
claude

환경 변수 - .env 파일로 관리
키체인 통합 - OS 보안 저장소 활용
OAuth 지원 - 자동 토큰 갱신
안전한 저장 - 암호화된 저장소

보안 주의: .env 파일을 .gitignore에 반드시 추가하세요. 인증 정보가 Git에 커밋되면 공개 저장소에서 즉시 악용될 수 있습니다.

연결 테스트

bash

# MCP 서버 연결 테스트

# 모든 서버 상태 확인
claude mcp status

# 특정 서버 테스트
claude mcp test postgres

# 상세 진단
claude mcp diagnose github --verbose

# 사용 가능한 도구 나열
claude mcp tools postgres

bash

# 테스트 결과 예시

$ claude mcp status

MCP Servers Status:
┌──────────────┬──────────┬─────────────────────┐
│ Name         │ Status   │ Uptime              │
├──────────────┼──────────┼─────────────────────┤
│ postgres     │ ✓ Active │ 2h 34m              │
│ filesystem   │ ✓ Active │ 2h 34m              │
│ github       │ ✗ Error  │ Connection refused  │
│ slack        │ ⊘ Off    │ Disabled            │
└──────────────┴──────────┴─────────────────────┘

상태 모니터링 - 실시간 연결 상태
도구 탐색 - 사용 가능한 기능 확인
진단 도구 - 문제 원인 파악
자동 재연결 - 연결 실패 시 재시도

다중 서버 관리

json

// 다중 MCP 서버 설정 예시
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/db"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "disabled": true  // 필요할 때만 활성화
    }
  }
}

bash

# 서버 관리 명령어

# 특정 서버 활성화/비활성화
claude mcp enable slack
claude mcp disable github

# 서버 재시작
claude mcp restart postgres

# 모든 서버 재시작
claude mcp restart --all

# 서버 로그 보기
claude mcp logs postgres --tail 50

동시 실행 - 여러 서버 병렬 사용
독립적 관리 - 개별 제어 가능
리소스 최적화 - 필요한 서버만 실행
통합 쿼리 - 여러 소스 동시 접근

MCP 문제 해결

bash

# 일반적인 문제와 해결 방법

# 문제 1: 서버가 시작되지 않음
$ claude mcp diagnose postgres

원인: command 경로가 잘못됨
해결: which npx로 정확한 경로 확인

# 문제 2: 인증 실패
원인: 환경 변수가 로드되지 않음
해결: .env 파일 경로 확인, claude --env-file .env 사용

# 문제 3: 타임아웃 발생
원인: 서버 응답 시간 초과
해결: timeout 값 증가 (설정 파일에 "timeout": 60000)

bash

# 디버그 모드 실행

# 상세 로그 출력
claude --debug mcp status

# 특정 서버 디버그
CLAUDE_LOG_LEVEL=debug claude mcp test github

# 로그 파일 위치
~/.claude/logs/mcp-postgres.log
~/.claude/logs/mcp-github.log

로그 확인: 문제 발생 시 가장 먼저 로그를 확인하세요. 대부분의 오류 원인이 로그에 명확히 표시됩니다.

포트 충돌: 일부 MCP 서버는 특정 포트를 사용합니다. 다른 프로세스가 해당 포트를 사용 중이면 연결에 실패할 수 있습니다.

다음 단계

MCP 서버 설정를 익혔습니다. 다음 주제로 넘어가보세요.

MCP 서버 설정

MCP 서버 설치

설정 파일 구성

인증 설정

연결 테스트

다중 서버 관리

MCP 문제 해결

다음 단계

로딩 중...

MCP 서버 설정

MCP 서버 설치

설정 파일 구성

인증 설정

연결 테스트

다중 서버 관리

MCP 문제 해결

다음 단계