Claude Code 설치 가이드 — npm 전역 설치와 MCP 서버 연동 6단계

Claude Code는 터미널에서 동작하는 AI 코딩 에이전트입니다. npm으로 한 번 설치하고 MCP 서버를 연동하면, Claude가 코드베이스를 읽고 파일을 고치는 데서 그치지 않고 외부 API와 한국 공문서 같은 실시간 데이터까지 직접 다룰 수 있습니다. 이 가이드는 npm install -g @anthropic-ai/claude-code부터 API 키 설정, settings.json MCP 연동, /mcp 연결 확인까지 6단계로 끝냅니다.

전체 그림 먼저 이해하기

설치를 시작하기 전에 각 구성 요소가 어떻게 맞물리는지 보면 설정 파일이 왜 그 위치에 있는지 이해하기 쉽습니다.

개발자 터미널
    │
    ▼
Claude Code CLI (npm 전역 설치)
    │  ~/.claude/settings.json의 mcpServers 읽기
    ▼
MCP 서버 (npx 또는 uvx로 실행)
    │  표준 입출력(stdio) 프로토콜
    ▼
외부 API / 한국 공공 데이터 / 문서 파일

핵심은 두 개의 실행 주체입니다. Claude Code 본체는 npm으로 한 번 전역 설치하고, 각 MCP 서버는 settings.json에 적어둔 command(주로 npx)로 세션이 시작될 때마다 자동 실행됩니다. 그래서 MCP 서버는 따로 설치하지 않아도 되고, 설정만 추가하면 됩니다.

준비물 확인

항목	최소 버전	확인 명령
Node.js	18.x 이상	node -v
npm	9.x 이상	npm -v
Anthropic API 키	—	console.anthropic.com

Node.js가 없다면 nodejs.org에서 LTS 버전을 설치하세요. npm은 Node.js에 포함되어 있어 따로 설치하지 않아도 됩니다.

단계별 설치 방법

1단계 — Node.js 및 npm 버전 확인

node -v   # v18.0.0 이상 확인
npm -v    # v9.0.0 이상 확인

버전이 낮으면 MCP 서버 실행 단계에서 예기치 않은 오류가 나기 쉽습니다. nvm(Node Version Manager)을 쓰고 있다면 nvm install --lts로 최신 LTS를 받고, 그렇지 않으면 공식 사이트에서 LTS를 재설치하세요. nvm으로 Node.js를 관리하면 다음 단계의 권한 오류도 함께 피할 수 있습니다.

2단계 — Claude Code CLI 전역 설치

npm install -g @anthropic-ai/claude-code

설치가 끝나면 claude 명령을 어느 디렉터리에서나 쓸 수 있습니다. 다음 명령으로 정상 설치를 확인하세요.

claude --version

버전 번호가 출력되면 성공입니다. claude: command not found가 나오면 PATH 문제이므로 아래 “흔한 오류” 표를 참고하세요.

권한 오류(EACCES)가 발생하면: macOS·Linux에서 전역 npm 디렉터리에 쓰기 권한이 없을 때 나타납니다. sudo npm install -g로 우회할 수 있지만, 근본 해결책은 nvm으로 Node.js를 사용자 홈에 설치해 sudo 없이 전역 설치가 되도록 하는 것입니다.

3단계 — Anthropic API 키 설정

Claude Code는 Anthropic API를 통해 동작합니다. 첫 실행 시 화면 안내에 따라 로그인/키 입력을 진행할 수도 있지만, API 키를 환경 변수로 한 번 설정해두면 매번 입력하지 않아도 됩니다.

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-..."

# 영구 적용: ~/.zshrc 또는 ~/.bashrc에 위 줄을 추가한 뒤
source ~/.zshrc

Windows PowerShell 환경이라면 아래와 같이 설정합니다.

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."

API 키는 Anthropic 콘솔의 API Keys 메뉴에서 발급합니다. 키는 비밀번호처럼 다뤄야 하며, 공개 저장소나 공유 파일에 그대로 넣지 마세요.

4단계 — Claude Code 첫 실행

작업할 프로젝트 디렉터리로 이동한 뒤 claude를 실행합니다.

cd ~/my-project
claude

처음 실행하면 약관 동의 화면이 나타납니다. 확인 후 대화 프롬프트가 열리면 준비가 끝난 것입니다. “이 프로젝트의 파일 목록을 보여줘”처럼 자연어로 입력해 동작을 확인해 보세요. 실행 위치(현재 디렉터리)가 Claude가 다루는 작업 폴더가 되므로, 반드시 대상 프로젝트 안에서 실행하는 것이 좋습니다.

5단계 — MCP 서버 설정 추가

MCP 서버는 ~/.claude/settings.json 파일의 mcpServers 블록에 추가합니다. 파일이나 디렉터리가 없으면 먼저 만드세요.

mkdir -p ~/.claude

아래는 한국 공문서 변환 MCP 서버(코르독)를 연결하는 가장 단순한 예시입니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    }
  }
}

여러 서버를 동시에 연결할 때는 mcpServers 객체 안에 항목을 나란히 추가합니다. 아래는 HWP 문서 처리 서버(HWP-MCP)를 함께 등록한 예시입니다. 서버 사이에 쉼표(,)를 빠뜨리면 JSON 문법 오류가 나니 주의하세요.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

API 키가 필요한 서버라면 env 블록에 환경 변수를 추가합니다. 이 키 역시 settings.json에 평문으로 저장되므로 파일 접근 권한에 유의하세요.

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-server-package"],
      "env": {
        "MY_API_KEY": "여기에_키_입력"
      }
    }
  }
}

6단계 — MCP 연결 확인

settings.json을 수정했다면 변경 사항은 다음 세션부터 반영됩니다. 기존 세션을 종료하고 새로 시작하세요.

claude   # 새 세션 시작

세션 안에서 다음 슬래시 명령을 입력합니다.

/mcp

연결된 서버 목록과 각 서버가 제공하는 도구(tool) 목록이 출력됩니다. 서버가 connected 상태로 표시되면 성공입니다. 목록에 서버가 보이지 않거나 연결 실패로 표시되면, 대부분 JSON 문법 오류이거나 세션을 재시작하지 않은 경우입니다.

흔한 오류와 해결 방법

오류 메시지	원인	해결 방법
claude: command not found	PATH에 npm 전역 bin이 없음	npm bin -g로 경로 확인 후 PATH에 추가, source로 재적용
EACCES permission denied	npm 전역 설치 권한 부족	nvm 사용 또는 npm 전역 디렉터리 권한 수정
Invalid API Key	API 키 오류 또는 환경 변수 미설정	echo $ANTHROPIC_API_KEY로 키 확인
MCP 서버가 /mcp 목록에 없음	JSON 문법 오류 또는 세션 미재시작	settings.json 유효성 확인 후 세션 재시작
spawn npx ENOENT	npx 실행 파일을 찾지 못함	Node.js 재설치 또는 npx 경로(PATH) 확인

settings.json 문법 빠른 점검

서버가 목록에 안 보이는 원인 1순위는 JSON 문법 오류(쉼표 누락, 중괄호 짝 안 맞음)입니다. 저장한 뒤 아래 명령으로 미리 검증하면 세션을 재시작하기 전에 잡아낼 수 있습니다.

node -e "require('/Users/$(whoami)/.claude/settings.json')" && echo "JSON 유효"

오류 없이 JSON 유효가 출력되면 문법은 정상입니다.

Claude Code CLI 주요 명령 정리

명령	설명
claude	현재 디렉터리에서 대화 세션 시작
claude "질문"	단일 질문 후 종료(비대화 모드)
/mcp	연결된 MCP 서버 및 도구 목록 확인
/help	사용 가능한 슬래시 명령 전체 목록
claude --version	설치된 버전 확인
claude update	최신 버전으로 업데이트

claude "질문" 형태의 비대화 모드는 셸 스크립트나 CI 파이프라인에 Claude Code를 끼워 넣을 때 유용합니다.

바로 연결할 수 있는 한국형 MCP 서버

설치를 마쳤다면 한국 데이터와 문서를 다루는 MCP 서버를 곧바로 연동해 보세요. 아래 세 서버는 별도 API 키 없이 npx만으로 실행됩니다.

서버	주요 기능	설치 명령
코르독 (KorDoc)	HWP·PDF·XLSX를 Markdown으로 변환	npx -y kordoc setup
HWP-MCP	한글(.hwp/.hwpx) 문서 읽기·편집	npx -y hwp-mcp
한포지 (HwpForge)	HWPX 문서 읽기·쓰기·변환	npx -y @hwpforge/mcp

각 서버를 mcpServers에 추가할 때는 위 5단계의 형식을 그대로 따르고, command는 npx, args는 표의 설치 명령에서 npx를 뺀 나머지 인자로 채우면 됩니다. 더 많은 한국형 서버는 개발자 도구 카테고리와 전체 서버 목록에서 찾을 수 있습니다.

자주 묻는 질문

Claude Code는 무료로 사용할 수 있나요?

Claude Code CLI 자체는 무료로 설치할 수 있지만, 실행하려면 Anthropic API 키가 필요합니다. API 사용은 토큰 단위로 과금됩니다. Anthropic 콘솔에서 무료 크레딧이 제공되는지 확인하세요.

Windows에서도 Claude Code를 설치할 수 있나요?

네, Windows에서도 Node.js와 npm이 설치되어 있으면 동일한 npm install 명령으로 설치할 수 있습니다. WSL2 환경을 사용하면 더 안정적으로 동작하는 경우가 많습니다.

npm install -g 없이 npx로 실행할 수 있나요?

Claude Code는 전역 설치를 권장합니다. npx로 매번 실행하면 응답 속도가 느려질 수 있고, MCP 설정 파일 경로가 달라질 수 있습니다. 가급적 npm install -g로 설치하세요.

MCP 서버를 추가한 뒤 Claude Code를 재시작해야 하나요?

네, settings.json을 수정한 뒤에는 세션을 종료하고 다시 시작해야 변경 사항이 반영됩니다.

Claude Code와 Claude Desktop의 차이점은 무엇인가요?

Claude Desktop은 GUI 애플리케이션이고, Claude Code는 터미널에서 동작하는 CLI 에이전트입니다. Claude Code는 코드베이스 탐색, 파일 편집, 명령 실행 등 개발 작업에 특화되어 있으며 MCP 서버 연동도 설정 파일로 직접 관리합니다.

설치 후 ‘claude: command not found’ 오류가 나면 어떻게 하나요?

npm의 전역 bin 경로가 PATH에 없을 때 발생합니다. npm bin -g 명령으로 경로를 확인한 뒤, 해당 경로를 셸 설정 파일(~/.zshrc 또는 ~/.bashrc)의 PATH에 추가하고 source 명령으로 다시 불러오세요.

다음 단계

설치가 끝났다면 MCP 서버로 기능을 넓혀 보세요. 한국 공문서를 AI로 처리하고 싶다면 코르독이나 한포지부터 시작하길 추천합니다. 더 많은 서버와 활용법은 전체 가이드 목록과 서버 목록에서 확인하세요.