MseeP.ai Security Assessment Badge

kospi-kosdaq-stock-server

PyPI version smithery badge

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

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

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)

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dragon1086 from gravatar.com dragon1086

Credits

Author: Sangrok Mun

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

dev legacy

Tags

finance korea kosdaq kospi krx mcp stock

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kospi_kosdaq_stock_server-0.4.1.tar.gz (152.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

kospi_kosdaq_stock_server-0.4.1-py3-none-any.whl (155.5 kB view details)

Uploaded Python 3

File details

Details for the file kospi_kosdaq_stock_server-0.4.1.tar.gz.

File metadata

File hashes

Hashes for kospi_kosdaq_stock_server-0.4.1.tar.gz
Algorithm Hash digest
SHA256 ba5628abd346daf2833ec18fedd206e46181188f0f49b502f864236b4f9a43b6
MD5 e14628c3518bb603e58d7f5c902b244d
BLAKE2b-256 4715f36cd2c42320ee4bd926886d5591eb7eee11f9141dcf5a6de2c71e88c178

See more details on using hashes here.

File details

Details for the file kospi_kosdaq_stock_server-0.4.1-py3-none-any.whl.

File metadata

File hashes

Hashes for kospi_kosdaq_stock_server-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 c6fbfdf9c07c872a3e3a61cd4ad3626bc3ca3e7a671c09eb4e229f35a2ef9a1d
MD5 2806fc553698dca8a2b299e00ed2f48c
BLAKE2b-256 1d3d6f226d17c06a5e9723c3c8c00c8739da815395bf9af57b4bbe02a0bcc7b6

See more details on using hashes here.

Release history Release notifications | RSS feed

0.4.2

2 files

This release

0.4.1 This release

2 files

0.4.0

2 files

0.3.37

2 files

0.3.36

2 files

0.3.35

2 files

0.3.34

2 files

0.3.33

2 files

0.3.32

2 files

0.3.31

2 files

0.3.30

2 files

0.3.29

2 files

0.3.28

2 files

0.3.27

2 files

0.3.26

2 files

0.3.25

2 files

0.3.24

2 files

0.3.23

2 files

0.3.22

2 files

0.3.21

2 files

0.3.20

2 files

0.3.19

2 files

0.3.18

2 files

0.3.17

2 files

0.3.16

2 files

0.3.15

2 files

0.3.14

2 files

0.3.13

2 files

0.3.12

2 files

0.3.11

2 files

0.3.10

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.2

2 files

0.2.1

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page