韩国股市数据 MCP 服务器

한국어 | English

MCP PyKRX

PyKRX 라이브러리를 활용한 한국 주식시장 데이터 Model Context Protocol(MCP) 서버입니다. 81개의 함수를 통해 주식, 채권, 지수, ETF, ETN, ELW, 선물 등 한국 금융시장의 모든 데이터에 AI가 접근할 수 있도록 합니다.

🆕 확장: KRX 공식 Open API + 정량 전략 + LEADERS DESK 웹앱

이 저장소는 기존 pykrx MCP 서버에 더해, KRX 공식 Open API 연동과 정량 전략 연구·데일리 트레이딩 웹서비스를 포함합니다.

• LEADERS DESK 웹앱 — 매 거래일 08:17경 자동 갱신되는 데일리 화면: 시장국면(D4), 보유 포트폴리오(브라우저 localStorage), 종목 발굴 2방식(모멘텀·추세 / TDA 위상수학), 매도 알림(시간청산+TDA), 오버나이트 단타(아침 매도·저녁 워치리스트). 화면 설계·전략 룰·데이터 파이프라인·검증 방법: docs/LEADERS_DESK.md
• 전략: F 리더(상대강도+52주고점+정배열) ∩ 20주선 눌림 진입 + 40거래일 시간청산/TDA 위상 청산 + D4 변동성 노출관리 — 워크포워드·룩어헤드 차단·비용 차감·통계 보정(날짜군집/짝지은차이)으로 검증
• 빌드/배치: app/ 패키지 (update_data 증분 → build_broad 전종목 → build_webapp HTML 생성), 백테스트는 backtest/*.py
• KRX 공식 Open API 도구 6종 (krx_official_*) — pykrx 스크래핑의 보조/검증 수단 (KRX_AUTH_KEY 필요)
• 초기 연구 과정은 backtest/README.md 참고.

复制

# 웹앱 빌드 후 브라우저로 확인
python -m app.batch.build_webapp --out backtest/trade.html
python -m http.server 8776   # → http://127.0.0.1:8776/backtest/trade.html

🚀 주요 특징

• 81개 함수 지원: PyKRX의 모든 기능을 MCP로 제공
• 스마트 캐싱: 데이터 유형별 최적화된 캐싱 전략
• Rate Limiting: KRX 서버 보호를 위한 자동 딜레이 관리
• 에러 복구: 자동 재시도 및 적응형 딜레이 조정
• 모듈화 설계: 기능별로 분리된 도구 모듈

사용 예시

AI 어시스턴트에게 다음과 같은 요청을 할 수 있습니다:

• 📊 주가 데이터 - "삼성전자의 최근 1년간 주가를 가져와주세요"
• 🔍 종목 검색 - "코스피 시장의 전체 종목 리스트를 보여주세요"
• 📈 시장 분석 - "어제 코스피와 코스닥의 거래량을 비교해주세요"
• 💹 재무 지표 - "현대차의 PER, PBR, 배당수익률을 조회해주세요"
• 📉 지수 정보 - "코스피200 지수의 최근 추이를 분석해주세요"
• 💰 채권 정보 - "국고채 3년물의 최근 수익률을 가져와주세요"

기능 데모

[데모 영상이 추가될 예정입니다]

지원 기능

빠른 시작 가이드

1. 사전 요구사항

[!IMPORTANT] PyKRX는 KRX와 네이버 금융에서 데이터를 스크래핑하는 방식으로 동작합니다.

• API 키 불필요: 별도의 인증이나 API 키가 필요하지 않습니다
• 사용 제한: 과도한 요청은 KRX 서버에서 IP 차단될 수 있으니 주의하세요
• 속도 제한: 대량 데이터 조회 시 자동으로 딜레이를 적용합니다
• 책임 소재: API 사용에 대한 책임은 사용자 본인에게 있습니다

2. 설치

# 저장소 복제
git clone https://github.com/YOUR_USERNAME/mcp-pykrx.git
cd mcp-pykrx

# [중요] Python 3.10 이상 사용 필수. 아래 'Python 3.10+ 설치 안내' 참고

# 가상 환경 생성
python3.10 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 패키지 설치
python3 -m pip install --upgrade pip
uv pip install -e .

Python 3.10+ 설치 안내

# Python 버전 확인 (3.10 이상 필요)
python3 --version

만약 Python 버전이 3.10 미만이라면, 아래 안내에 따라 Python 3.10 이상을 설치하세요:

macOS

• 공식 웹사이트에서 최신 Python 설치 파일을 다운로드: https://www.python.org/downloads/macos/
• 또는 Homebrew를 사용하는 경우:
  复制

  brew install python@3.10
  

  설치 후 python3.10 명령어를 사용해야 할 수 있습니다.

Windows

• 공식 웹사이트에서 최신 Python 설치 파일을 다운로드 및 실행: https://www.python.org/downloads/windows/
• 설치 시 "Add Python to PATH" 옵션을 반드시 체크하세요.
• 설치 후 터미널을 재시작하고 python 또는 python3 명령어를 사용하세요.

Linux (Ubuntu/Debian)

• 패키지 목록을 업데이트하고 Python 3.10 설치:
  复制

  sudo apt update
  sudo apt install python3.10 python3.10-venv python3.10-distutils
  

• python3.10 명령어를 사용해야 할 수 있습니다.

Linux (Fedora/CentOS/RHEL)

• Python 3.10 설치:
  复制

  sudo dnf install python3.10
  

IDE 통합

MCP PyKRX는 IDE 통합을 통해 AI 어시스턴트와 함께 사용하도록 설계되었습니다.

Claude Desktop 설정 방법

1. 햄버거 메뉴(☰) > Settings > Developer > "Edit Config" 버튼 클릭
2. 아래 설정을 추가:

{
  "mcpServers": {
    "mcp-pykrx": {
      "command": "YOUR_LOCATION/.venv/bin/mcp-pykrx",
      "env": {
        "HOST": "0.0.0.0",
        "PORT": "8001",
        "TRANSPORT": "stdio",
        "LOG_LEVEL": "INFO",
        "MCP_SERVER_NAME": "mcp-pykrx",
        "CACHE_DIR": "~/.mcp-pykrx/cache",
        "REQUEST_DELAY": "1.0"
      }
    }
  }
}

[!NOTE]

• YOUR_LOCATION: 가상환경이 설치된 실제 경로로 변경
• Windows 경로 예시: C:\\Users\\YourName\\mcp-pykrx\\.venv\\Scripts\\mcp-pykrx.exe

주요 환경 변수

• HOST: 서버 호스트 (기본값: 0.0.0.0)
• PORT: 서버 포트 (기본값: 8001)
• TRANSPORT: 전송 방식 (stdio 권장, http로 설정시 streamable-http 지원)
• LOG_LEVEL: 로깅 레벨 (INFO, DEBUG, WARNING, ERROR)
• MCP_SERVER_NAME: 서버 이름
• CACHE_DIR: 캐시 저장 디렉토리 (기본값: ~/.mcp-pykrx/cache)
• REQUEST_DELAY: 요청 간 딜레이 시간(초) (기본값: 1.0)
• MAX_RETRIES: 요청 실패 시 최대 재시도 횟수 (기본값: 3)

Streamable-HTTP 설정 (선택사항)

HTTP 모드로 서버를 실행하려면 TRANSPORT 환경변수를 http로 설정하세요:

{
  "mcpServers": {
    "mcp-pykrx": {
      "command": "YOUR_LOCATION/.venv/bin/mcp-pykrx",
      "env": {
        "HOST": "0.0.0.0",
        "PORT": "8001",
        "TRANSPORT": "http",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

HTTP 모드에서는 http://HOST:PORT/sse 엔드포인트를 통해 MCP 프로토콜을 사용할 수 있습니다.

데이터 캐싱 시스템

시스템 아키텍처

graph TD
    A[데이터 요청] --> B{캐시 존재?}
    B -->|Yes| C{캐시 유효?}
    B -->|No| D[KRX/네이버 스크래핑]
    C -->|Valid| E[캐시 데이터 반환]
    C -->|Expired| D
    D --> F[데이터 파싱 및 정제]
    F --> G[캐시 저장]
    G --> H[데이터 반환]
    H --> I[딜레이 적용]
    I --> J[다음 요청 준비]

캐싱 구조

~/.mcp-pykrx/cache/
├── stock/
│   ├── ticker_list/          # 종목 리스트 캐시
│   │   ├── kospi_20240101.json
│   │   └── kosdaq_20240101.json
│   ├── ohlcv/                 # OHLCV 데이터 캐시
│   │   ├── 005930_20240101_20240131.json
│   │   └── 000660_20240101_20240131.json
│   ├── fundamental/           # 재무지표 캐시
│   │   ├── 005930_20240101.json
│   │   └── 000660_20240101.json
│   └── trading/               # 투자자별 매매동향 캐시
│       ├── 005930_20240101_20240131.json
│       └── investor_summary_20240101.json
├── index/
│   ├── price/                 # 지수 시세 캐시
│   │   ├── 1001_20240101_20240131.json  # 코스피
│   │   └── 2001_20240101_20240131.json  # 코스닥
│   └── portfolio/             # 지수 구성종목 캐시
│       ├── kospi200_20240101.json
│       └── kosdaq150_20240101.json
├── bond/
│   ├── treasury_yields/       # 국고채 수익률 캐시
│   │   └── 20240101_20240131.json
│   └── corporate_yields/      # 회사채 수익률 캐시
│       └── 20240101_20240131.json
└── etf/
    ├── list/                  # ETF 목록 캐시
    │   └── all_20240101.json
    └── portfolio/             # ETF 구성종목 캐시
        └── 069500_20240101.json

캐싱 정책

• 종목 리스트: 1일 캐시 (영업일 기준 갱신)
• OHLCV 데이터: 당일 데이터는 1시간, 과거 데이터는 영구 캐시
• 재무 지표: 1일 캐시
• 지수 정보: 1시간 캐시
• 채권 수익률: 1일 캐시

도구

PyKRX 도구

• stock: 주식 시세 및 종목 정보
• bond: 채권 수익률 정보
• index: 시장 지수 정보
• etf: ETF 관련 정보
• trading: 투자자별 매매동향
• shorting: 공매도 정보

KRX 공식 Open API 도구 (보조 수단)

pykrx(스크래핑)와 별개로 KRX 정보데이터시스템 공식 Open API(data-dbg.krx.co.kr)를 보조 데이터 경로로 제공합니다. .env의 KRX_AUTH_KEY를 사용하며, pykrx의 전종목 열거가 막혔을 때 등 신뢰 가능한 공식 데이터로 보완할 수 있습니다.

[!IMPORTANT] 공식 API는 인증키 발급과 별개로 데이터셋(서비스)별 이용신청·승인이 필요합니다 (openapi.krx.co.kr → 로그인 → '서비스 이용' → API 이용신청, 보통 1일 내 승인). 미승인 서비스 호출 시 401 Unauthorized API Call이 반환됩니다. 하루 10,000콜 제한, 데이터는 2010년부터 제공됩니다.

문제 해결 및 디버깅

일반적인 문제

• IP 차단 문제:

  • 과도한 API 호출로 KRX에서 IP가 차단될 수 있습니다
  • REQUEST_DELAY 환경 변수를 2.0 이상으로 늘려보세요
  • 대량 데이터 조회 시 배치 작업을 나눠서 실행하세요
  • 차단 해제는 KRX 데이터사업부에 문의해야 하며 원칙적으로 불가능합니다

• 데이터 조회 실패:

  • 영업일이 아닌 날짜를 조회하면 데이터가 없을 수 있습니다
  • 상장폐지된 종목은 일반 조회 함수에서 검색되지 않습니다
  • 일부 오래된 데이터는 KRX에서 제공하지 않을 수 있습니다

• 속도 저하:

  • 첫 조회는 스크래핑으로 인해 느릴 수 있습니다 (종목당 약 1-2초)
  • 캐시를 활성화하면 이후 조회가 빠릅니다
  • 대량 조회 시 배치 크기를 줄이고 딜레이를 늘리세요

• 인코딩 문제:

  • 종목명이 깨져 보이면 시스템 로케일을 확인하세요
  • UTF-8 인코딩을 사용하는지 확인하세요

디버깅 도구

# 상세 로깅 활성화
export LOG_LEVEL=DEBUG

# 캐시 디렉토리 확인
ls -la ~/.mcp-pykrx/cache/

# 캐시 삭제 (문제 해결용)
rm -rf ~/.mcp-pykrx/cache/

# 연결 테스트
python -m mcp_pykrx test-connection

# 단일 종목 조회 테스트
python -m mcp_pykrx test-ticker 005930

로그 분석

# 최근 에러 로그 확인
tail -f ~/.mcp-pykrx/logs/error.log

# 요청 로그 확인
tail -f ~/.mcp-pykrx/logs/request.log

# 캐시 히트율 확인
cat ~/.mcp-pykrx/logs/stats.log | grep "cache_hit"

사용 시 주의사항

법적 고지사항

[!WARNING] 본 도구는 비공식 라이브러리입니다.

• KRX가 공식적으로 제공하는 API가 아닙니다
• 웹 스크래핑 방식으로 데이터를 수집합니다
• KRX 이용약관 위반 가능성을 고려해야 합니다

사용 권장사항

1. 도의적 사용: 무분별한 API 호출은 자제해 주세요
2. 참고용 데이터: 결과물은 참고용으로만 사용하세요
3. 투자 책임: 투자 결정에 대한 책임은 사용자에게 있습니다
4. 속도 제한: 요청 간 충분한 딜레이를 유지하세요
5. 공식 API: 상업적 용도라면 KRX 공식 API 사용을 권장합니다

속도 제한 가이드

# 권장 사용 패턴
import time
from pykrx import stock

# 단일 종목 조회
df = stock.get_market_ohlcv("20240101", "20240131", "005930")

# 다수 종목 조회 (딜레이 필수)
tickers = stock.get_market_ticker_list("20240101")
for ticker in tickers:
    df = stock.get_market_ohlcv("20240101", "20240131", ticker)
    time.sleep(1)  # 1초 딜레이 권장

보안 및 성능

보안 고려사항

• IP 주소가 KRX 서버에 노출됩니다
• 과도한 요청 시 IP 차단될 수 있습니다
• VPN 사용 시에도 차단 가능성이 있습니다
• 로그 파일에 요청 이력이 저장됩니다

성능 최적화

• 캐싱 활용: 동일 데이터 재조회 시 캐시 사용
• 배치 처리: 대량 데이터는 시간대를 나눠서 조회
• 병렬 처리 지양: 동시 요청은 차단 위험을 높입니다
• 딜레이 준수: 요청 간 1초 이상 딜레이 권장

데이터 소스

본 프로젝트는 다음 소스에서 데이터를 수집합니다:

1. KRX 정보데이터시스템 (http://data.krx.co.kr)

   • 주식 시세
   • 시장 지수
   • 투자자별 매매동향
   • ETF 정보

2. 네이버 금융 (https://finance.naver.com)

   • 종목별 상세 정보
   • 재무 지표
   • 기업 개요

기여하기

기여를 환영합니다! 기여하시려면:

1. 저장소를 포크하세요
2. 기능 브랜치를 만드세요 (git checkout -b feature/amazing-feature)
3. 변경사항을 커밋하세요 (git commit -m 'Add amazing feature')
4. 브랜치에 푸시하세요 (git push origin feature/amazing-feature)
5. Pull Request를 생성하세요

개발 가이드라인

• Python 3.10 이상 사용
• PEP 8 스타일 가이드 준수
• 타입 힌트 사용 권장
• 단위 테스트 작성 필수
• 문서화 주석 작성

라이선스

이 프로젝트는 비상업적, 개인적, 연구, 학습, 비영리 목적에 한해 사용할 수 있습니다. 상업적 사용, 재배포, 2차 저작물의 상업적 이용은 엄격히 금지됩니다. 자세한 내용은 LICENSE 파일을 참고하세요.

면책 조항

• 본 프로젝트는 공식 KRX 제품이 아닙니다
• KRX와 네이버는 본 프로젝트와 무관합니다
• 데이터의 정확성을 보장하지 않습니다
• 투자 손실에 대한 책임을 지지 않습니다
• 서비스 중단이나 데이터 오류 가능성이 있습니다

참고 자료

• PyKRX 원본 프로젝트
• KRX 정보데이터시스템
• 네이버 금융
• Model Context Protocol 문서

문의 및 지원

• GitHub Issues: 버그 리포트 및 기능 제안
• GitHub Discussions: 일반적인 질문 및 토론
• Email: support@example.com (문의용)

Made with ❤️ for the Korean Stock Market Community