kospi-kosdaq-stock-server

kospi-kosdaq-stock-server

一个从 KRX Data Marketplace 提供 KOSPI/KOSDAQ 股票数据的 MCP 服务。

v0.3.0 新功能

自 2024 年 12 月 27 日起，KRX Data Marketplace 要求通过 Kakao/Naver 登录才能访问数据。本版本实现了：

• 直接集成 KRX API，支持 Kakao OAuth 登录
• 基于 Playwright 的无头浏览器，用于身份验证
• 自动会话管理，会话超时为 4 小时，并自动重新登录
• 核心功能不再依赖 pykrx

功能

• 查询 KOSPI/KOSDAQ 股票代码和名称
• 获取股票 OHLCV（开盘价/最高价/最低价/收盘价/成交量）数据
• 获取市值数据
• 获取基本面数据（PER/PBR/股息率）
• 按投资者类型（机构、外国投资者、个人）获取交易量
• 获取指数 OHLCV 数据（KOSPI、KOSDAQ 指数）

要求

• Python 3.10+
• Kakao 账号（必须关闭双重身份验证）
• Playwright Chromium 浏览器

环境变量

# Required: Kakao login credentials
KAKAO_ID=your_kakao_id
KAKAO_PW=your_kakao_password

重要提示：必须关闭 Kakao 账号的双重身份验证（2FA）。 首次登录时，可能需要通过 KakaoTalk 批准登录请求。

安装

前置条件

# Install Playwright and Chromium browser
pip install playwright
playwright install chromium

通过 Smithery 安装

npx -y @smithery/cli install @dragon1086/kospi-kosdaq-stock-server --client claude

手动安装

# Create and activate a virtual environment
uv venv .venv
source .venv/bin/activate  # On Unix/macOS
# .venv\Scripts\activate   # On Windows

# Install the package
uv pip install kospi-kosdaq-stock-server

# Install Playwright browser
playwright install chromium

Claude Desktop 配置

macOS

1. 打开配置文件：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 添加服务配置：

{
  "mcpServers": {
    "kospi-kosdaq": {
      "command": "uvx",
      "args": ["kospi_kosdaq_stock_server"],
      "env": {
        "KAKAO_ID": "your_kakao_id",
        "KAKAO_PW": "your_kakao_password"
      }
    }
  }
}

Windows

1. 打开 %APPDATA%/Claude/claude_desktop_config.json 中的配置文件

2. 添加与上文相同的配置

3. 重启 Claude Desktop

可用工具

load_all_tickers

加载 KOSPI 和 KOSDAQ 的所有股票代码和名称。

• 无需参数
• 返回：将股票代码映射到股票名称的字典

get_stock_ohlcv

获取指定股票的 OHLCV（开盘价/最高价/最低价/收盘价/成交量）数据。

• fromdate（字符串，必填）：开始日期（YYYYMMDD）
• todate（字符串，必填）：结束日期（YYYYMMDD）
• ticker（字符串，必填）：股票代码（例如："005930"）
• adjusted（布尔值，可选）：是否使用复权价格（默认：True）

get_stock_market_cap

获取指定股票的市值数据。

• fromdate（字符串，必填）：开始日期（YYYYMMDD）
• todate（字符串，必填）：结束日期（YYYYMMDD）
• ticker（字符串，必填）：股票代码

get_stock_fundamental

获取指定股票的基本面数据（PER/PBR/股息率）。

• fromdate（字符串，必填）：开始日期（YYYYMMDD）
• todate（字符串，必填）：结束日期（YYYYMMDD）
• ticker（字符串，必填）：股票代码

get_stock_trading_volume

按投资者类型获取指定股票的交易量。

• fromdate（字符串，必填）：开始日期（YYYYMMDD）
• todate（字符串，必填）：结束日期（YYYYMMDD）
• ticker（字符串，必填）：股票代码
• detail（布尔值，可选）：若为 true，则返回 12 种投资者类型；若为 false（默认），则返回 5 种汇总类型

get_index_ohlcv

获取市场指数的 OHLCV 数据。

• fromdate（字符串，必填）：开始日期（YYYYMMDD）
• todate（字符串，必填）：结束日期（YYYYMMDD）
• ticker（字符串，必填）：指数代码（例如，KOSPI 为 "1001"，KOSDAQ 为 "2001"）
• freq（字符串，可选）：频率——"d"（每日）、"m"（每月）、"y"（每年）。默认："d"

可用资源

stock://tickers

返回所有 KOSPI/KOSDAQ 股票代码和名称。

stock://index-tickers

返回指数代码信息：

• KOSPI：1001，KOSPI 200：1028，KOSPI 100：1034，KOSPI 50：1035
• KOSDAQ：2001，KOSDAQ 150：2203

stock://data-sources

返回当前数据源状态。

Docker 支持

使用 Docker Compose

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

Docker 环境变量

创建一个 .env 文件：

KAKAO_ID=your_kakao_id
KAKAO_PW=your_kakao_password

故障排查

“KakaoTalk 登录通知”弹窗

首次登录时，Kakao 可能要求通过 KakaoTalk 批准：

1. 使用 headless=False 运行，以查看浏览器
2. 在 KakaoTalk 中批准登录
3. Cookie 将保存下来，供后续会话使用

401 未授权 / 会话已过期

会话约 4 小时后过期。服务会自动续期，但如果续期失败：

1. 删除 ~/.krx_session.json
2. 重启服务

Linux 无头环境

# Install required packages on Ubuntu/Debian
apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
    libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2

架构

┌─────────────────────────────────────────────────────┐
│                MCP Server (FastMCP)                 │
│              kospi_kosdaq_stock_server.py           │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│               KRXDataClient                         │
│  - get_market_ohlcv()                               │
│  - get_market_cap()                                 │
│  - get_market_fundamental()                         │
│  - get_market_trading_volume_by_date()              │
│  - get_index_ohlcv()                                │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│             KakaoAuthManager                        │
│  - Playwright headless browser                      │
│  - Kakao OAuth login                                │
│  - Session cookie management                        │
│  - Auto re-login on session expiry (4h)             │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│           KRX Data Marketplace                      │
│             data.krx.co.kr                          │
└─────────────────────────────────────────────────────┘

已知限制

• 不支持启用了 2FA 的 Kakao 账户
• 首次登录可能需要通过 KakaoTalk 批准
• 会话有效期：约 4 小时（支持自动续期）
• 尚未实现 Naver 登录

使用示例

Human: Please load all available stock tickers.
Assistant: I'll load all KOSPI and KOSDAQ stock tickers.

> Using tool 'load_all_tickers'...
Successfully loaded 2,738 stock tickers.

Human: Show me Samsung Electronics' stock data for December 2024.
Assistant: I'll retrieve Samsung Electronics' (005930) OHLCV data.

> Using tool 'get_stock_ohlcv'...
Date        Open      High      Low       Close     Volume
2024-12-20  53,800    54,200    53,500    53,900    8,234,521
2024-12-19  54,000    54,300    53,700    53,800    7,123,456
...

许可证

MIT 许可证

参与贡献

欢迎提交问题和拉取请求！

更新日志

v0.3.0（2025-01-04）

• 重大变更：核心功能移除了 pykrx 依赖
• 新增 KRX Data Marketplace 与 Kakao OAuth 的直接集成
• 新增基于 Playwright 的无头身份验证
• 新增自动会话管理
• 新增指数 OHLCV 支持

v0.2.x

• 基于 pykrx 的实现（因 KRX 要求登录而弃用）