pykrx-mcp
Korean stock market data (KOSPI/KOSDAQ) with ETF tracking and fundamental analysis
Open source Open in the app JSON README (API)
About
Korean stock market data (KOSPI/KOSDAQ) with ETF tracking and fundamental analysis
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- sharebook-kr
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Stars
- 3
- Forks
- 5
- Last push
- 2026-02-01T02:52:09Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:23
- Updated
- 2026-08-29 04:01:23
- Origin id
io.github.sharebook-kr/pykrx-mcp
README
# pykrx-mcp
[](https://badge.fury.io/py/pykrx-mcp)
[](https://www.python.org/downloads/)
[](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/sharebook-kr/pykrx-mcp)
한국 주식 시장 데이터를 AI 에이전트에게 제공하는 MCP (Model Context Protocol) 서버입니다.
[pykrx](https://github.com/sharebook-kr/pykrx) 라이브러리를 기반으로 KOSPI, KOSDAQ, KONEX 시장의 주가, 재무제표, 투자자별 수급, 공매도 등 다양한 데이터를 ChatGPT와 Claude에서 자연어로 조회할 수 있습니다.
---
## ☕ 후원하기
프로젝트가 도움이 되었다면 개발자를 응원해주세요!
[](https://github.com/sponsors/sharebook-kr)
---
## 1. 시작하기
### 1.1 Claude Desktop에서 사용하기
#### 자동 설치 (권장)
MCP Registry를 통한 원클릭 설치:
```bash
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`
```json
{
"mcpServers": {
"pykrx": {
"command": "uvx",
"args": ["pykrx-mcp"]
}
}
}
```
설정 후 Claude Desktop을 재시작하면 바로 사용할 수 있습니다.
---
## 2. 지원하는 데이터 및 API
> 모든 API는 [pykrx 라이브러리](https://github.com/sharebook-kr/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](https://github.com/sharebook-kr/pykrx)**: 한국 주식 시장 데이터 수집
- **[FastMCP](https://github.com/jlowin/fastmcp)**: MCP 서버 프레임워크
- **MCP (Model Context Protocol)**: AI 에이전트와의 통신 프로토콜
---
## 6. 개발자 정보
### 6.1 로컬 개발 환경 설정
자세한 내용은 [DEVELOPMENT.md](DEVELOPMENT.md)를 참고하세요.
```bash
# 저장소 클론
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](https://github.com/sharebook-kr/pykrx)**: 한국 주식 시장 데이터 수집 라이브러리 (본 프로젝트의 기반)
- **[MCP](https://modelcontextprotocol.io/)**: Model Context Protocol 공식 문서