Kospi Kosdaq Stock Server

🚀 KOSPI-KOSDAQ Stock Server

A MCP server that provides KOSPI/KOSDAQ stock data using FastMCP.

🚀 Quick Start

This is a MCP server that offers KOSPI/KOSDAQ stock data through FastMCP. It allows users to look up stock codes and names, retrieve OHLCV data, market capitalization data, fundamental data, and trading volume by investor type for specific stocks.

✨ Features

• Look up stock codes and names of KOSPI/KOSDAQ.
• Get OHLCV (Open/High/Low/Close/Volume) data of specific stocks.
• Get market capitalization data of specific stocks.
• Get fundamental data (PER/PBR/Dividend Yield) of specific stocks.
• Get trading volume by investor type of specific stocks.

📦 Installation

The installation of this package requires uv.

Install via Smithery

To install via Smithery:

smithery install @dragon1086/kospi-kosdaq-stock-server

💻 Usage Examples

Basic Usage

Get all stock list

from kospi_kosdaq_stock_server import load_all_tickers

tickers = load_all_tickers()
print(tickers)

Output:

[{'stock_code': '005930', 'company_name': 'Samsung Electronics'}, {'stock_code': '000660', 'company_name': 'SK Hynix'}, ...]

Get detailed stock information

from kospi_kosdaq_stock_server import get_stock_info

stock_info = get_stock_info('005930')
print(stock_info)

Output:

{
    'Basic Information': {
        'Company Name': 'Samsung Electronics',
        'Listed Market': 'KOSPI',
        'Industry Classification': 'Semiconductor',
        'Founded Date': '1987-02-24',
        'Number of Employees': 214836,
        'Official Website': 'https://www.samsung.com/semiconductor'
    },
    'Financial Data': {
        'Latest Stock Price': 73800.0,
        'Price-Earnings Ratio': 15.89,
        'Price-Book Ratio': 2.14,
        'Dividend Yield': 0.56
    }
}

Get historical price data

from kospi_kosdaq_stock_server import get_stock_price_data

prices = get_stock_price_data('005930', start_date='2024-01-01', end_date='2024-02-28')
print(prices)

Output:

Advanced Usage

Batch get historical price data of multiple stocks

from kospi_kosdaq_stock_server import get_multiple_stock_price_data

stock_codes = ['005930', '000660', '233780']
prices = get_multiple_stock_price_data(stock_codes, start_date='2024-01-01', end_date='2024-02-28')
print(prices)

Output:

{
    '005930': DataFrame(...),
    '000660': DataFrame(...),
    '233780': DataFrame(...)
}

Use environment variables

Set the following environment variables in the terminal:

export KOSPI_API_KEY=your_kospi_api_key
export KOSDAQ_API_KEY=your_kosdaq_api_key

Then run the Python script.

📚 Documentation

Available Tools

• load_all_tickers - Load all stock codes and names of KOSPI and KOSDAQ into memory.

  • No parameters.

• get_stock_ohlcv - Get OHLCV data of a specific stock.

  • fromdate (string, required): Start date (YYYYMMDD).
  • todate (string, required): End date (YYYYMMDD).
  • ticker (string, required): Stock code.
  • adjusted (boolean, optional): Whether to use adjusted prices (True: adjusted, False: unadjusted). Default is True.

• get_stock_market_cap - Get market capitalization data of a specific stock.

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

• get_stock_fundamental - Get fundamental data of a specific stock.

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

• get_stock_trading_volume - Get trading volume by investor type of a specific stock.

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

Configuration Instructions

Environment Variables

This package requires the following environment variables for configuration:

• KOSPI_API_KEY: API key for KOSPI.
• KOSDAQ_API_KEY: API key for KOSDAQ.

If these environment variables are not set, you can use default values or specify them manually in the code.

Install Dependencies

Install the necessary Python packages:

pip install python-koapy

🔧 Technical Details

Error Handling

Error when environment variables are not set

If KOSPI_API_KEY or KOSDAQ_API_KEY is not set, an error will occur. You can use default values or specify them manually in the code.