Claude Code에서 MCP 연결하는 법

Claude Code에 MCP를 연결한다는 것

Claude Code는 터미널에서 동작하는 Anthropic의 공식 코딩 에이전트입니다. 여기에 MCP 서버를 연결하면 Claude가 외부 데이터·도구를 직접 호출할 수 있게 됩니다. 연결 방법은 간단합니다. 설정 파일에 서버 정보를 한 블록 추가하면 끝납니다. 이 글에서는 가장 안정적인 방식인 ~/.claude/settings.json 직접 편집을 단계별로 안내합니다.

1단계 — 설정 파일 열기

홈 디렉터리의 ~/.claude/settings.json을 엽니다. 파일이 없다면 새로 만듭니다. 이 파일은 Claude Code 전역 설정을 담으며, MCP 서버 목록도 여기에 둘 수 있습니다.

mkdir -p ~/.claude
open -e ~/.claude/settings.json   # macOS, 없으면 새로 생성됨

2단계 — mcpServers 블록 추가

mcpServers 키 아래에 연결할 서버를 추가합니다. 각 서버는 이름을 키로 하고, command/args/env를 값으로 갖습니다. 아래는 DART 공시 MCP와 공공데이터 MCP를 동시에 붙이는 예시입니다.

{
  "mcpServers": {
    "dart": {
      "command": "npx",
      "args": ["-y", "dart-mcp-server"],
      "env": { "DART_API_KEY": "여기에_DART_키" }
    },
    "korea-public-data": {
      "command": "npx",
      "args": ["-y", "korea-public-data-mcp"],
      "env": { "DATA_GO_KR_KEY": "여기에_공공데이터_키" }
    }
  }
}

command: 서버 실행 명령입니다. npm 패키지로 배포된 서버는 보통 npx를 씁니다.
args: 실행 인자입니다. -y는 npx 설치 확인 프롬프트를 건너뜁니다.
env: API 키 같은 비밀값을 환경 변수로 주입합니다. 키는 이 자리에만 넣고 외부에 노출하지 마세요.

3단계 — Claude Code 재시작

설정을 저장한 뒤 실행 중인 Claude Code 세션을 종료하고 다시 실행합니다. 재시작 시 Claude가 설정을 다시 읽어 새 MCP 서버에 연결합니다.

claude   # 새 세션 시작

4단계 — 연결 확인

세션 안에서 /mcp 명령을 입력하면 현재 연결된 MCP 서버와 도구 목록을 볼 수 있습니다. 서버가 정상이라면 상태가 connected로 표시됩니다. 이후 “DART에서 삼성전자 최근 공시 찾아줘”처럼 자연어로 요청하면 Claude가 해당 도구를 자동 호출합니다.

자주 막히는 지점

서버가 안 보일 때: JSON 문법 오류(쉼표 누락, 따옴표 빠짐)가 가장 흔합니다. 설정 파일이 유효한 JSON인지 확인하세요.
인증 오류: env의 키 이름이 서버가 기대하는 변수명과 정확히 일치해야 합니다. 각 서버 상세 페이지의 설치 탭에서 정확한 변수명을 확인하세요.
npx 지연: 첫 실행 시 패키지 다운로드로 몇 초가 걸릴 수 있습니다. 잠시 기다리면 됩니다.