KOSPI/KOSDAQ Stock Server

Proporciona datos de acciones de KOSPI/KOS

GitHub
73
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

kospi-kosdaq-stock-server

PyPI version smithery badge

Un servidor MCP que proporciona datos de acciones KOSPI/KOSDAQ del Mercado de Datos de KRX.

Novedades en v0.3.0

Desde el 27 de diciembre de 2024, el Mercado de Datos de KRX requiere inicio de sesión con Kakao/Naver para acceder a los datos. Esta versión implementa:

  • Integración directa con la API de KRX con inicio de sesión OAuth de Kakao
  • Navegador headless basado en Playwright para autenticación
  • Gestión automática de sesiones con tiempo de espera de 4 horas y re-inicio de sesión automático
  • Sin dependencia de pykrx para funcionalidad principal

Características

  • Consultar símbolos de cotización y nombres de KOSPI/KOSDAQ
  • Recuperar datos OHLCV (Apertura/Máximo/Mínimo/Cierre/Volumen) para acciones
  • Recuperar datos de capitalización de mercado
  • Recuperar datos fundamentales (PER/PBR/Rendimiento de Dividendos)
  • Recuperar volumen de negociación por tipo de inversor (institucional, extranjero, individual)
  • Recuperar datos OHLCV de índices (índices KOSPI, KOSDAQ)

Requisitos

  • Python 3.10+
  • Cuenta de Kakao (la verificación en dos pasos debe estar desactivada)
  • Navegador Chromium de Playwright

Variables de Entorno

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

Importante: Su cuenta de Kakao debe tener la verificación en dos pasos (2FA) desactivada. En el primer inicio de sesión, es posible que deba aprobar la solicitud de inicio de sesión a través de KakaoTalk.

Instalación

Requisitos Previos

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

Instalación a través de Smithery

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

Instalación Manual

# 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

Configuración para Claude Desktop

macOS

  1. Abra el archivo de configuración:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
  1. Agregue la configuración del servidor:
{
  "mcpServers": {
    "kospi-kosdaq": {
      "command": "uvx",
      "args": ["kospi_kosdaq_stock_server"],
      "env": {
        "KAKAO_ID": "your_kakao_id",
        "KAKAO_PW": "your_kakao_password"
      }
    }
  }
}

Windows

  1. Abra el archivo de configuración en %APPDATA%/Claude/claude_desktop_config.json

  2. Agregue la misma configuración que arriba

  3. Reinicie Claude Desktop

Herramientas Disponibles

load_all_tickers

Carga todos los símbolos de cotización y nombres para KOSPI y KOSDAQ.

  • No requiere argumentos
  • Devuelve: Diccionario que mapea códigos de cotización a nombres de acciones

get_stock_ohlcv

Recupera datos OHLCV (Apertura/Máximo/Mínimo/Cierre/Volumen) para una acción específica.

  • fromdate (cadena, obligatorio): Fecha de inicio (AAAAMMDD)
  • todate (cadena, obligatorio): Fecha de fin (AAAAMMDD)
  • ticker (cadena, obligatorio): Símbolo de cotización de la acción (por ejemplo, "005930")
  • adjusted (booleano, opcional): Usar precios ajustados (predeterminado: True)

get_stock_market_cap

Recupera datos de capitalización de mercado para una acción específica.

  • fromdate (cadena, obligatorio): Fecha de inicio (AAAAMMDD)
  • todate (cadena, obligatorio): Fecha de fin (AAAAMMDD)
  • ticker (cadena, obligatorio): Símbolo de cotización de la acción

get_stock_fundamental

Recupera datos fundamentales (PER/PBR/Rendimiento de Dividendos) para una acción específica.

  • fromdate (cadena, obligatorio): Fecha de inicio (AAAAMMDD)
  • todate (cadena, obligatorio): Fecha de fin (AAAAMMDD)
  • ticker (cadena, obligatorio): Símbolo de cotización de la acción

get_stock_trading_volume

Recupera volumen de negociación por tipo de inversor para una acción específica.

  • fromdate (cadena, obligatorio): Fecha de inicio (AAAAMMDD)
  • todate (cadena, obligatorio): Fecha de fin (AAAAMMDD)
  • ticker (cadena, obligatorio): Símbolo de cotización de la acción
  • detail (booleano, opcional): Si es true, devuelve 12 tipos de inversores; si es false (predeterminado), devuelve 5 tipos agregados

get_index_ohlcv

Recupera datos OHLCV para índices de mercado.

  • fromdate (cadena, obligatorio): Fecha de inicio (AAAAMMDD)
  • todate (cadena, obligatorio): Fecha de fin (AAAAMMDD)
  • ticker (cadena, obligatorio): Símbolo del índice (por ejemplo, "1001" para KOSPI, "2001" para KOSDAQ)
  • freq (cadena, opcional): Frecuencia - "d" (diaria), "m" (mensual), "y" (anual). Predeterminado: "d"

Recursos Disponibles

stock://tickers

Devuelve todos los símbolos de cotización y nombres de KOSPI/KOSDAQ.

stock://index-tickers

Devuelve información de símbolos de índices:

  • KOSPI: 1001, KOSPI 200: 1028, KOSPI 100: 1034, KOSPI 50: 1035
  • KOSDAQ: 2001, KOSDAQ 150: 2203

stock://data-sources

Devuelve el estado actual de la fuente de datos.

Soporte Docker

Usando Docker Compose

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

Variables de Entorno para Docker

Cree un archivo .env:

KAKAO_ID=your_kakao_id
KAKAO_PW=your_kakao_password

Solución de Problemas

Ventana emergente "Notificación de inicio de sesión de KakaoTalk"

En el primer inicio de sesión, Kakao puede requerir aprobación a través de KakaoTalk:

  1. Ejecute con headless=False para ver el navegador
  2. Apruebe el inicio de sesión en KakaoTalk
  3. Las cookies se guardarán para sesiones futuras

401 No Autorizado / Sesión Expirada

La sesión expira después de ~4 horas. El servidor se renueva automáticamente, pero si falla:

  1. Elimine ~/.krx_session.json
  2. Reinicie el servidor

Entorno Headless de 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

Arquitectura

┌─────────────────────────────────────────────────────┐
│                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                          │
└─────────────────────────────────────────────────────┘

Limitaciones Conocidas

  • Las cuentas de Kakao con 2FA habilitado no son compatibles
  • El primer inicio de sesión puede requerir aprobación de KakaoTalk
  • Validez de la sesión: ~4 horas (renovación automática compatible)
  • El inicio de sesión con Naver aún no está implementado

Ejemplo de Uso

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
...

Licencia

Licencia MIT

Contribuciones

¡Las incidencias y solicitudes de extracción son bienvenidas!

Registro de Cambios

v0.3.0 (2025-01-04)

  • Cambio importante: Se eliminó la dependencia de pykrx para la funcionalidad principal
  • Se agregó integración directa con el Mercado de Datos de KRX con OAuth de Kakao
  • Se agregó autenticación headless basada en Playwright
  • Se agregó gestión automática de sesiones
  • Se agregó soporte OHLCV de índices

v0.2.x

  • Implementación basada en pykrx (obsoleta debido al requisito de inicio de sesión de KRX)