pykrx-mcp

pykrx-mcp

为 AI Agent 提供韩国股票市场数据的 MCP（Model Context Protocol）服务。

基于 pykrx 库，可通过 ChatGPT 和 Claude 使用自然语言查询 KOSPI、KOSDAQ、KONEX 市场的股价、财务报表、投资者交易情况、卖空等多种数据。

---

☕ 赞助

如果这个项目对您有所帮助，请支持开发者！

---

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 外国投资

• 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 Agent 优化

支持 MCP 协议，可直接在 ChatGPT 和 Claude 中使用。

---

5. 技术栈

• Python 3.10+
• pykrx：韩国股票市场数据采集
• FastMCP：MCP 服务框架
• MCP（Model Context Protocol）：与 AI Agent 通信的协议

---

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 官方文档