Claude Code 완전 설치 가이드 2026 - Node.js부터 CLAUDE.md, MCP 서버, 권한 설정까지
Claude Code 완전 설치 가이드: 첫 실행까지 완벽 정리
Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트입니다. 파일 읽기·수정, 명령어 실행, Git 작업까지 자연어로 지시할 수 있어 개발 생산성을 획기적으로 높여줍니다. 이 가이드에서는 설치부터 프로젝트 설정, MCP 서버 연동, 권한 모드 구성까지 한 번에 정리합니다.
1단계: Node.js 설치 및 환경 확인
Claude Code는 Node.js 18 이상이 필요합니다. 먼저 현재 환경을 확인하세요.
node —version
npm —version
Node.js가 설치되어 있지 않거나 버전이 낮다면 공식 사이트에서 LTS 버전을 설치합니다.
- Windows: nodejs.org에서 LTS 설치 파일(.msi)을 다운로드하여 실행합니다.- macOS: Homebrew를 사용합니다.
brew install node@20- Linux (Ubuntu/Debian):curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs설치 후
node —version으로 v18 이상인지 반드시 확인하세요.
2단계: Claude Code 설치
npm을 통해 전역으로 설치합니다.
npm install -g @anthropic-ai/claude-code
설치가 완료되면 버전을 확인합니다.
claude —version
설치 후 최초 실행 시 Anthropic 계정 인증이 진행됩니다. 브라우저가 열리며 로그인하면 자동으로 토큰이 저장됩니다.
# 프로젝트 디렉토리에서 최초 실행
cd ~/my-project
claude
API 키를 직접 사용하려면 환경 변수를 설정합니다.
# .bashrc 또는 .zshrc에 추가
export ANTHROPIC_API_KEY=“YOUR_API_KEY”
3단계: CLAUDE.md 프로젝트 설정
CLAUDE.md는 Claude Code가 프로젝트 컨텍스트를 이해하는 핵심 파일입니다. 프로젝트 루트에 생성하면 매 세션마다 자동으로 로드됩니다.
CLAUDE.md 파일 구조
# 프로젝트명 - Claude Code 설정
프로젝트 개요
- 기술 스택: React 18, TypeScript, Tailwind CSS
- 패키지 매니저: pnpm
- Node 버전: 20.x
코딩 컨벤션
- 함수형 컴포넌트만 사용
- 파일명은 kebab-case 사용
- 테스트 파일은 tests 디렉토리에 배치
빌드 및 실행
pnpm install
pnpm dev # 개발 서버
pnpm build # 프로덕션 빌드
pnpm test # 테스트 실행
중요 규칙
- API 키를 코드에 직접 포함하지 마세요
- 모든 컴포넌트에 TypeScript 타입을 명시하세요
console.log 대신 프로젝트 로거를 사용하세요
CLAUDE.md 배치 위치별 적용 범위
| 위치 | 적용 범위 | 용도 |
|---|---|---|
프로젝트루트/CLAUDE.md | 해당 프로젝트 전체 | 프로젝트 컨벤션, 빌드 명령어 |
~/.claude/CLAUDE.md | 모든 프로젝트 (글로벌) | 공통 규칙, 개인 선호 설정 |
하위폴더/CLAUDE.md | 해당 폴더 작업 시 | 모듈별 특화 규칙 |
MCP(Model Context Protocol) 서버를 연동하면 Claude Code에 외부 도구(GitHub, DB, API 등)를 확장할 수 있습니다.
MCP 설정 파일 생성
프로젝트 루트에 .claude/settings.json 파일을 만듭니다.
{
“mcpServers”: {
“github”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-github”],
“env”: {
“GITHUB_PERSONAL_ACCESS_TOKEN”: “YOUR_API_KEY”
}
},
“filesystem”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-filesystem”, “/path/to/allowed/dir”]
},
“postgres”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-postgres”],
“env”: {
“POSTGRES_CONNECTION_STRING”: “postgresql://user:pass@localhost:5432/mydb”
}
}
}
}
MCP 서버 동작 확인
Claude Code를 실행한 뒤 /mcp 명령으로 연결 상태를 확인할 수 있습니다.
claude
# 세션 내에서 입력:
/mcp
연결된 서버 목록과 사용 가능한 도구가 표시됩니다.
5단계: 권한 모드 구성
Claude Code는 세 가지 권한 모드를 지원합니다. 보안과 생산성 사이의 균형을 맞춰 선택하세요.
| 모드 | 설명 | 적합한 상황 |
|---|---|---|
| **Ask (기본)** | 파일 수정·명령 실행마다 승인 요청 | 처음 사용하거나 민감한 프로젝트 |
| **Auto-edit** | 파일 수정은 자동, 셸 명령은 승인 | 코드 작성 중심의 일반 개발 |
| **Yolo** | 모든 작업을 자동 실행 | 실험·프로토타입 환경 |
/permissions 명령으로 변경하거나, 설정 파일에서 지정할 수 있습니다.
# 세션 내에서 권한 모드 변경
/permissions
또는 실행 시 플래그 지정
claude —allowedTools “Edit,Write,Bash(git *)“
특정 도구만 자동 허용하려면 .claude/settings.json에 추가합니다.
{
“permissions”: {
“allow”: [
“Edit”,
“Write”,
“Bash(npm test)”,
“Bash(git status)”,
“Bash(git diff *)”
],
“deny”: [
“Bash(rm -rf *)”,
“Bash(git push *)”
]
}
}
Pro Tips: 파워 유저를 위한 팁
- 슬래시 명령어 활용:
/help로 전체 명령어 목록 확인,/compact로 대화 압축,/clear로 세션 초기화- 빠른 모드 전환:/fast를 입력하면 동일한 Opus 모델에서 더 빠른 출력을 받을 수 있습니다.- 메모리 시스템 활용: “이걸 기억해줘”라고 말하면 Claude Code가~/.claude/projects/에 영구 메모리를 저장합니다. 다음 세션에서도 유지됩니다.- 파이프라인 통합:claude -p “이 코드의 테스트를 작성해줘” —output-format json으로 CI/CD 파이프라인에 통합할 수 있습니다.- Git 워크플로우: “커밋 메시지 작성해줘”나 “PR 설명 만들어줘”처럼 Git 작업을 자연어로 지시하세요.- 멀티 파일 작업: “src 폴더의 모든 컴포넌트에서 console.log를 제거해줘”처럼 범위가 넓은 작업도 한 번에 처리됩니다.
Troubleshooting: 자주 발생하는 오류
| 오류 | 원인 | 해결 방법 |
|---|---|---|
command not found: claude | 전역 설치 경로가 PATH에 없음 | npm config get prefix로 경로 확인 후 PATH에 추가 |
ANTHROPIC_API_KEY not set | API 키 미설정 | 환경 변수 설정 또는 claude 실행 후 브라우저 인증 |
Node.js version not supported | Node 18 미만 사용 | nvm install 20 && nvm use 20으로 업그레이드 |
| MCP 서버 연결 실패 | 설정 파일 경로 또는 JSON 형식 오류 | .claude/settings.json 문법 검증 후 Claude Code 재시작 |
| 권한 거부 반복 발생 | permissions 설정이 너무 제한적 | /permissions에서 필요한 도구를 allow 목록에 추가 |
Q1. Claude Code는 무료로 사용할 수 있나요?
Claude Code는 Anthropic의 Claude Pro, Team, 또는 Enterprise 구독이 필요합니다. Pro 플랜(월 $20)에서는 사용량 제한이 있으며, API 키를 직접 사용하면 토큰 기반 종량제로 과금됩니다. Max 플랜(월 $100 또는 $200)에서는 더 높은 사용량 한도가 제공됩니다.
Q2. CLAUDE.md 파일을 Git에 커밋해도 되나요?
네, 프로젝트 루트의 CLAUDE.md는 팀 전체 컨벤션을 공유하기 위해 Git에 커밋하는 것이 권장됩니다. 다만 ~/.claude/CLAUDE.md는 개인 설정 파일이므로 커밋 대상이 아닙니다. API 키나 민감 정보는 CLAUDE.md에 절대 포함하지 마세요.
Q3. MCP 서버를 직접 만들 수 있나요?
네, MCP는 오픈 프로토콜이므로 누구나 커스텀 서버를 만들 수 있습니다. TypeScript SDK(@modelcontextprotocol/sdk)를 사용하면 간단히 구현할 수 있으며, 회사 내부 API나 사내 도구를 Claude Code에 연결하는 데 활용할 수 있습니다. 공식 GitHub 저장소에서 다양한 레퍼런스 서버 예제를 확인하세요.