kospi-kosdaq-stock-server

An MCP server that provides KOSPI/KOSDAQ stock data from KRX Data Marketplace.

What's New in v0.3.0

Since December 27, 2024, KRX Data Marketplace requires Kakao/Naver login for data access. This version implements:

• Direct KRX API integration with Kakao OAuth login
• Playwright-based headless browser for authentication
• Automatic session management with 4-hour timeout and auto re-login
• No more pykrx dependency for core functionality

Features

• Lookup KOSPI/KOSDAQ ticker symbols and names
• Retrieve OHLCV (Open/High/Low/Close/Volume) data for stocks
• Retrieve market capitalization data
• Retrieve fundamental data (PER/PBR/Dividend Yield)
• Retrieve trading volume by investor type (institutional, foreign, individual)
• Retrieve index OHLCV data (KOSPI, KOSDAQ indices)

Requirements

• Python 3.10+
• Kakao account (2FA must be disabled)
• Playwright Chromium browser

Environment Variables

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

Important: Your Kakao account must have 2-step verification (2FA) disabled. On first login, you may need to approve the login request via KakaoTalk.

Installation

Prerequisites

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

Installing via Smithery

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

Manual Installation

# 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

Configuration for Claude Desktop

macOS

1. Open the config file:

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

2. Add the server configuration:

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

Windows

1. Open the config file at %APPDATA%/Claude/claude_desktop_config.json

2. Add the same configuration as above

3. Restart Claude Desktop

Available Tools

load_all_tickers

Loads all ticker symbols and names for KOSPI and KOSDAQ.

• No arguments required
• Returns: Dictionary mapping ticker codes to stock names

get_stock_ohlcv

Retrieves OHLCV (Open/High/Low/Close/Volume) data for a specific stock.

• fromdate (string, required): Start date (YYYYMMDD)
• todate (string, required): End date (YYYYMMDD)
• ticker (string, required): Stock ticker symbol (e.g., "005930")
• adjusted (boolean, optional): Use adjusted prices (default: True)

get_stock_market_cap

Retrieves market capitalization data for a specific stock.

• fromdate (string, required): Start date (YYYYMMDD)
• todate (string, required): End date (YYYYMMDD)
• ticker (string, required): Stock ticker symbol

get_stock_fundamental

Retrieves fundamental data (PER/PBR/Dividend Yield) for a specific stock.

• fromdate (string, required): Start date (YYYYMMDD)
• todate (string, required): End date (YYYYMMDD)
• ticker (string, required): Stock ticker symbol

`

... View full README on GitHub