pykrx MCP를 Claude Desktop에 연결하기 — KOSPI·KOSDAQ 데이터 설정 가이드

Q: Windows에서도 pykrx MCP 서버가 정상 동작하나요?

네, 동작합니다. 단 Windows에서는 Python을 PATH에 등록해야 하며, 설정 파일 경로가 %APPDATA%\Claude\claude_desktop_config.json로 다르니 주의하세요.

Q: Claude가 MCP 서버를 인식하지 못하면 어떻게 해야 하나요?

JSON 문법 오류가 가장 흔한 원인입니다. claude_desktop_config.json을 JSON 유효성 검사기로 확인하세요. 또한 Python 실행 경로를 절대 경로로 지정했는지, Claude Desktop을 완전히 재시작했는지 확인합니다.

Q: pykrx MCP 서버를 Claude Code나 Cursor에서도 쓸 수 있나요?

네. Claude Code는 --mcp-server 플래그로, Cursor는 settings.json의 mcp 항목으로 동일하게 등록할 수 있습니다. 서버 실행 명령 자체는 Claude Desktop과 동일합니다.

pykrx MCP 서버를 Claude Desktop에 연결하면 KOSPI·KOSDAQ 종목의 시세·거래량 데이터를 자연어로 바로 조회·분석할 수 있습니다. 별도 API 키 발급이 필요 없고, KRX(한국거래소) 공개 데이터를 그대로 활용하므로 Python 환경만 갖춰져 있으면 빠르게 연결을 마칠 수 있습니다. 이 문서는 설치 확인 → 설정 파일 작성 → 연결 검증 → 오류 해결 순서로 진행합니다.

pykrx MCP가 해결하는 문제

종목별 시세, 거래량, 외국인·기관 매매 동향을 확인하려면 기존에는 보통 KRX 홈페이지 접속 → 파일 다운로드 → 스프레드시트 가공이라는 단계를 반복해야 했습니다.

pykrx 는 이 조회 과정을 Python 함수 호출로 줄여 주는 오픈소스 라이브러리입니다.
MCP(Model Context Protocol) 서버로 감싸면 Claude가 이 라이브러리를 직접 호출해 데이터를 가져오고, 받은 결과를 그 자리에서 요약·분석합니다.

즉 “삼성전자 최근 한 달 거래량 추세를 알려줘” 같은 요청 한 번으로, 데이터 수집과 해석을 한 흐름에서 처리할 수 있습니다.

사용자 질문
   │
   ▼
Claude Desktop
   │  MCP 프로토콜 (stdio)
   ▼
pykrx MCP 서버
   │  pykrx 호출
   ▼
KRX(한국거래소) 공개 데이터

준비물

항목	버전·조건	확인 방법
Python	3.10 이상	`python --version`
pip 또는 uv	패키지 설치 도구	`pip --version` / `uv --version`
Claude Desktop	최신 버전	claude.ai/download
인터넷 연결	KRX 접근 필요	사내망이라면 방화벽 예외 확인

pykrx는 KRX 공개 페이지에서 데이터를 가져오므로 API 키 발급은 필요 없습니다. 데이터 제공 범위와 갱신 시점에 관한 세부 사항은 아래 자주 묻는 질문에서 다룹니다.

단계별 설정 방법

1단계 — Python 환경과 pykrx 설치 확인

터미널(macOS: 터미널, Windows: PowerShell)에서 Python 버전을 먼저 확인합니다. 3.10 미만이면 먼저 Python을 업그레이드하세요.

python --version
# 예: Python 3.11.x

pykrx 라이브러리를 설치하고, import가 되는지로 설치를 검증합니다.

pip install pykrx
python -c "import pykrx; print('pykrx OK')"

pykrx OK 가 출력되면 라이브러리 설치는 정상입니다.

2단계 — pykrx MCP 서버 패키지 설치

pykrx를 MCP 서버로 노출하는 패키지를 설치합니다. pip 와 uv 중 익숙한 도구를 쓰면 됩니다.

# pip 방식
pip install pykrx-mcp

# uv 방식 (가상환경을 함께 관리)
uv add pykrx-mcp

설치 후 서버 모듈이 실행되는지 확인합니다.

python -m pykrx_mcp --help

패키지마다 실행 모듈명·명령이 다를 수 있습니다. 위 명령에서 오류가 난다면 임의로 추측하지 말고, 설치한 패키지의 README/문서에 적힌 정확한 실행 방법을 그대로 따르세요. 이 가이드의 이후 설정 예시는 python -m pykrx_mcp 실행 방식을 기준으로 합니다.

3단계 — Claude Desktop 설정 파일 열기

Claude Desktop의 MCP 서버는 JSON 설정 파일로 관리됩니다. 운영체제별 경로는 다음과 같습니다.

운영체제	설정 파일 경로
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

파일이 없으면 새로 만들고, 있으면 텍스트 에디터로 엽니다.

# macOS에서 VS Code로 바로 열기
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

4단계 — mcpServers에 pykrx 서버 추가

설정 파일이 비어 있을 때는 아래 전체를 붙여넣습니다.

{
  "mcpServers": {
    "pykrx": {
      "command": "python",
      "args": ["-m", "pykrx_mcp"]
    }
  }
}

이미 다른 서버가 등록돼 있을 때는 mcpServers 객체 안에 pykrx 항목만 추가하고, 항목 사이에 쉼표(,)를 빠뜨리지 않도록 주의합니다.

Windows에서는 python 절대 경로 권장

Windows에서 python 이 PATH에 없거나 여러 버전이 섞여 있으면 Claude가 서버를 실행하지 못할 수 있습니다. 이때는 command 에 Python 실행 파일의 절대 경로를 지정하세요.

{
  "mcpServers": {
    "pykrx": {
      "command": "C:\\Users\\사용자이름\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
      "args": ["-m", "pykrx_mcp"]
    }
  }
}

JSON에서 Windows 경로의 역슬래시(\)는 \\ 로 이스케이프해야 합니다.

uv 로 설치했다면 command 를 uv 로 바꾸고 그에 맞게 args 를 조정해야 합니다. 구체적인 실행 형식은 설치한 패키지 문서를 따르세요.

5단계 — Claude Desktop 재시작 및 연결 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료합니다. 창만 닫는 것으로는 설정이 다시 읽히지 않습니다.

macOS: Cmd + Q
Windows: 트레이 아이콘 우클릭 → 종료

다시 실행한 후, 입력창 주변에 MCP 도구(아이콘)가 표시되는지 확인하고 아래처럼 질문해 봅니다.

“삼성전자(005930) 최근 거래일 종가와 거래량을 알려줘.”

Claude가 pykrx MCP 서버를 호출해 실제 수치로 답하면 연결이 정상적으로 완료된 것입니다.

설정 후 바로 해볼 수 있는 분석

질문 예시	pykrx 내부 동작
”KOSPI 시가총액 상위 10개 종목 알려줘”	시가총액 데이터 조회
”카카오 최근 60일 주가 추이 분석해줘”	일별 OHLCV 조회 후 추세 분석
”최근 거래일 외국인 순매수 상위 종목은?”	외국인 거래 동향 조회
”KOSDAQ 종목들의 섹터 분포 보여줘”	섹터 정보 조회

질문에 종목명·종목코드와 함께 조회 기준 날짜를 명시하면 의도한 거래일 데이터를 더 정확히 받을 수 있습니다.

흔한 오류와 해결 방법

`ModuleNotFoundError: No module named 'pykrx_mcp'`

Claude가 실행하는 Python 환경에 pykrx-mcp 가 설치되어 있지 않은 경우입니다. 특히 가상환경을 쓸 때, 활성화하지 않은 다른 Python에 설치하면 이 오류가 납니다.

# Claude가 쓸 Python 경로 확인
which python   # macOS/Linux
where python   # Windows

# 확인된 경로의 Python으로 직접 설치
/확인된/python/경로 -m pip install pykrx-mcp

설치 후 claude_desktop_config.json 의 command 에 위에서 확인한 절대 경로를 그대로 넣으면 환경 불일치를 피할 수 있습니다.

설정 변경 후에도 서버가 안 잡힐 때 (JSON 문법 오류)

설정 파일에 문법 오류가 있으면 Claude Desktop이 MCP 서버를 읽지 못합니다. 가장 흔한 실수는 마지막 항목 뒤에 남은 쉼표와 닫는 중괄호 누락입니다. jsonlint.com 같은 검사기에 파일 내용을 붙여넣어 유효성을 확인하세요.

KRX 데이터 조회 실패·타임아웃

장 마감 직후 KRX가 데이터를 갱신하는 시간대에는 응답이 느리거나 실패할 수 있습니다. 잠시 후 다시 시도하거나, 직전 거래일 날짜를 명시해 조회하세요.

함께 쓰면 좋은 한국 금융 MCP 서버

pykrx MCP가 시세·거래량 중심이라면, 재무제표나 공시까지 필요할 때는 아래 서버를 함께 활용해 보세요.

한국 주식 MCP 서버 — DART·KRX 공식 API 기반. 재무제표·공시 데이터 조회. API 키 발급 필요(opendart.fss.or.kr).
한국 금융 MCP — 한국은행 ECOS, DART, KRX, 국토부 실거래가를 통합한 종합 금융 데이터 서버.
한국 주식 분석기 MCP — 6대 투자 대가 전략(워런 버핏, 피터 린치 등)으로 KOSPI/KOSDAQ 종목을 자동 분석. 설치: npx @mrbaeksang/korea-stock-analyzer-mcp

더 많은 서버는 금융 카테고리에서 찾을 수 있습니다.

자주 묻는 질문

pykrx MCP 서버를 사용하려면 별도 API 키가 필요한가요?

아니요. pykrx는 KRX(한국거래소) 공개 데이터를 스크레이핑 방식으로 가져오기 때문에 별도의 API 키 발급 없이 사용할 수 있습니다. 다만 과도한 요청은 KRX 서버에 부담을 줄 수 있으므로 적정 주기를 유지하는 것이 좋습니다.

pykrx로 조회할 수 있는 데이터 범위는 어디까지인가요?

KOSPI·KOSDAQ·KONEX 시장의 종목별 일별 OHLCV(시가·고가·저가·종가·거래량), 섹터 정보, 시가총액, 외국인·기관 매매 동향 등을 조회할 수 있습니다. 당일 실시간 데이터는 지원하지 않으며, 전 거래일 종가까지 제공됩니다.

Windows에서도 pykrx MCP 서버가 정상 동작하나요?

네, 동작합니다. 단 Windows에서는 Python을 PATH에 등록하거나 설정 파일의 command 에 절대 경로를 지정해야 하며, 설정 파일 경로가 %APPDATA%\Claude\claude_desktop_config.json 으로 macOS와 다르니 주의하세요.

pykrx MCP와 Korea Stock MCP 서버의 차이는 무엇인가요?

pykrx MCP는 KRX 공개 데이터를 스크레이핑 방식으로 제공해 API 키가 필요 없고 빠르게 시작할 수 있습니다. 반면 Korea Stock MCP 서버는 DART·KRX 공식 API를 사용하며 재무제표 같은 심층 데이터를 제공하지만 API 키 발급이 필요합니다.

Claude가 MCP 서버를 인식하지 못하면 어떻게 해야 하나요?

JSON 문법 오류가 가장 흔한 원인입니다. claude_desktop_config.json 을 JSON 유효성 검사기로 확인하세요. 그다음 Python 실행 경로를 절대 경로로 지정했는지, Claude Desktop을 완전히 재시작했는지 차례로 점검합니다.

pykrx MCP 서버를 Claude Code나 Cursor에서도 쓸 수 있나요?

서버를 실행하는 명령(python -m pykrx_mcp) 자체는 동일하므로, 각 클라이언트의 MCP 설정 방식에 맞춰 같은 command/args를 등록하면 됩니다. 클라이언트별 MCP 등록 위치와 형식은 해당 클라이언트의 공식 문서를 확인하세요.

다음 단계

더 많은 한국 금융 MCP 서버를 금융 카테고리에서 탐색하세요.
재무제표·공시 데이터가 필요하다면 한국 주식 MCP 서버를 추가로 설정해 보세요.
새로운 한국산 MCP 서버를 발견했다면 MCP모아에 등록해 커뮤니티와 공유하세요.