pykrx-mcp

한국 주식 시장 데이터를 AI 에이전트에게 제공하는 MCP (Model Context Protocol) 서버입니다.

pykrx 라이브러리를 기반으로 KOSPI, KOSDAQ, KONEX 시장의 주가, 재무제표, 투자자별 수급, 공매도 등 다양한 데이터를 ChatGPT와 Claude에서 자연어로 조회할 수 있습니다.

# ☕ 후원하기

프로젝트가 도움이 되었다면 개발자를 응원해주세요!

# 1. 시작하기

# # 1.1 Claude Desktop에서 사용하기

# # # 자동 설치 (권장)

MCP Registry를 통한 원클릭 설치:

npx @modelcontextprotocol/inspector install pykrx-mcp

# # # 수동 설치

Claude Desktop 설정 파일을 직접 수정:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pykrx": {
      "command": "uvx",
      "args": ["pykrx-mcp"]
    }
  }
}

설정 후 Claude Desktop을 재시작하면 바로 사용할 수 있습니다.

# 2. 지원하는 데이터 및 API

모든 API는 pykrx 라이브러리를 기반으로 구현되었습니다.

# # 2.1 주식 데이터 (Stock Data)

# # # 2.1.1 종목 정보

• get_market_ticker_list: 시장별 종목 코드 조회
• get_market_ticker_name: 종목 코드로 종목명 조회

# # # 2.1.2 가격 데이터

• get_stock_ohlcv: 개별 종목 OHLCV (시가/고가/저가/종가/거래량)
• get_market_ohlcv_by_date: 특정 일자 전종목 시세
• get_market_price_change: 기간별 전종목 가격 변동

# # # 2.1.3 시가총액

• get_market_cap_by_date: 개별 종목 시가총액 조회

# # # 2.1.4 재무 지표

• get_market_fundamental_by_date: PER, PBR, EPS, DIV, BPS, DPS

# # # 2.1.5 투자자별 거래

• get_market_trading_value_by_date: 종목별 투자자 수급 (거래대금)
• get_market_trading_volume_by_investor: 투자자별 거래량
• get_market_trading_value_by_investor: 투자자별 거래대금
• get_market_net_purchases_of_equities: 투자자별 순매수 상위 종목

# # 2.2 지수 데이터 (Index Data)

# # # 2.2.1 지수 정보

• get_index_ticker_list: 지수 티커 목록
• get_index_ticker_name: 지수 이름 조회
• get_index_portfolio_deposit_file: 지수 구성 종목

# # # 2.2.2 지수 가격

• get_index_ohlcv: 지수 OHLCV 데이터

# # # 2.2.3 지수 지표

• get_index_fundamental: 지수 PER/PBR/배당수익률

# # 2.3 공매도 데이터 (Short Selling)

• get_shorting_status_by_date: 종목별 공매도 현황
• get_shorting_volume_by_ticker: 전종목 공매도 거래량
• get_shorting_balance_top50: 공매도 잔고 상위 50
• get_shorting_volume_top50: 공매도 거래 비중 상위 50

# # 2.4 외국인 투자 (Foreign Investment)

• get_exhaustion_rates_of_foreign_investment: 외국인 보유량 및 한도소진률

# # 2.5 ETF 데이터

• get_etf_ticker_list: ETF 종목 리스트
• get_etf_ohlcv_by_date: ETF OHLCV 데이터

총 23개의 데이터 조회 도구 지원

# 3. 사용 예시

# # 3.1 주가 조회

개별 종목 주가

"삼성전자 최근 한달 주가 보여줘"
"SK하이닉스 2024년 1월 OHLCV 데이터"
"카카오 지난주 주가 움직임 분석해줘"

시장 전체 시세

"코스피 전종목 오늘 시세 보여줘"
"코스닥 상위 10개 종목 가격 변동률"

# # 3.2 시가총액 & 거래량

"삼성전자 시가총액이 얼마야?"
"삼성전자 최근 한달 거래량 추이"
"네이버 거래대금 분석해줘"

# # 3.3 재무 지표

"삼성전자 PER, PBR 알려줘"
"삼성전자 배당수익률 얼마야?"
"네이버 최근 EPS는?"

# # 3.4 투자자별 수급 분석

"삼성전자 외국인 매수세 어때?"
"카카오 최근 기관 수급 분석"
"코스피 개인 투자자가 많이 산 종목"
"외국인이 순매수한 상위 10개 종목"

# # 3.5 공매도 분석

"삼성전자 공매도 비중 얼마야?"
"코스피 공매도 상위 종목 알려줘"
"공매도 잔고가 가장 높은 종목은?"

# # 3.6 지수 조회

"코스피 지수 최근 한달 추이"
"코스닥 150 지수 PER은?"
"반도체 섹터 지수 구성 종목 알려줘"

# # 3.7 외국인 투자

"삼성전자 외국인 보유 비중은?"
"외국인 한도소진률 높은 종목"

# # 3.8 종목 검색

"코스피 종목 리스트"
"005930 종목명이 뭐야?"
"오늘 거래된 ETF 리스트"

# 4. 주요 특징

# # 4.1 자연어 대화형 인터페이스

복잡한 API 문법 없이 일상 언어로 데이터를 조회할 수 있습니다.

# # 4.2 실시간 한국 주식 시장 데이터

KRX(한국거래소)의 최신 데이터를 제공합니다.

# # 4.3 다양한 분석 기능

• 가격 추이 분석
• 투자자별 수급 분석
• 재무 지표 비교
• 공매도 현황 분석

# # 4.4 AI 에이전트 최적화

ChatGPT와 Claude에서 바로 사용할 수 있도록 MCP 프로토콜을 지원합니다.

# 5. 기술 스택

• Python 3.10+
• pykrx: 한국 주식 시장 데이터 수집
• FastMCP: MCP 서버 프레임워크
• MCP (Model Context Protocol): AI 에이전트와의 통신 프로토콜

# 6. 개발자 정보

# # 6.1 로컬 개발 환경 설정

자세한 내용은 DEVELOPMENT.md를 참고하세요.

#  저장소 클론
git clone https://github.com/sharebook-kr/pykrx-mcp.git
cd pykrx-mcp

#  의존성 설치
uv pip install -e ".[dev]"

#  테스트 실행
uv run pytest

#  서버 실행
uv run pykrx-mcp

# # 6.2 기여하기

이슈 및 풀 리퀘스트를 환영합니다!

# 7. 라이선스

MIT License - 자유롭게 사용하세요!

# 8. 관련 프로젝트

• pykrx: 한국 주식 시장 데이터 수집 라이브러리 (본 프로젝트의 기반)
• MCP: Model Context Protocol 공식 문서