kospi-kosdaq-stock-server

<a href="https://glama.ai/mcp/servers/i1judi5h55">

</a>

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

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

# Build and run
docker-compose up -d
View logs
docker-compose logs -f

Environment Variables for Docker

Create a .env file:

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

# 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

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

```