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

bashCopy code
# 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

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

Installing via Smithery

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

Manual Installation

bashCopy code
# 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:

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

2. Add the server configuration:

jsonCopy code
{
  "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

get_stock_trading_volume

Retrieves trading volume by investor type for a specific stock.

• fromdate (string, required): Start date (YYYYMMDD)
• todate (string, required): End date (YYYYMMDD)
• ticker (string, required): Stock ticker symbol
• detail (boolean, optional): If true, returns 12 investor types; if false (default), returns 5 aggregated types

get_index_ohlcv

Retrieves OHLCV data for market indices.

• fromdate (string, required): Start date (YYYYMMDD)
• todate (string, required): End date (YYYYMMDD)
• ticker (string, required): Index ticker (e.g., "1001" for KOSPI, "2001" for KOSDAQ)
• freq (string, optional): Frequency - "d" (daily), "m" (monthly), "y" (yearly). Default: "d"

Available Resources

stock://tickers

Returns all KOSPI/KOSDAQ ticker symbols and names.

stock://index-tickers

Returns index ticker information:

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

stock://data-sources

Returns current data source status.

Docker Support

Using Docker Compose

bashCopy code
# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

Environment Variables for Docker

Create a .env file:

bashCopy code
KAKAO_ID=your_kakao_id
KAKAO_PW=your_kakao_password

Troubleshooting

"KakaoTalk login notification" popup

On first login, Kakao may require approval via KakaoTalk:

1. Run with headless=False to see the browser
2. Approve the login in KakaoTalk
3. Cookies will be saved for future sessions

401 Unauthorized / Session Expired

Session expires after ~4 hours. The server auto-renews, but if it fails:

1. Delete ~/.krx_session.json
2. Restart the server

Linux Headless Environment

bashCopy code
# 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

Architecture

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

Known Limitations

• Kakao accounts with 2FA enabled are not supported
• First login may require KakaoTalk approval
• Session validity: ~4 hours (auto-renewal supported)
• Naver login is not yet implemented

Usage Example

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

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

License

MIT License

Contributing

Issues and pull requests are welcome!

Changelog

v0.3.0 (2025-01-04)

• Breaking: Removed pykrx dependency for core functionality
• Added KRX Data Marketplace direct integration with Kakao OAuth
• Added Playwright-based headless authentication
• Added automatic session management
• Added index OHLCV support

v0.2.x

• pykrx-based implementation (deprecated due to KRX login requirement)