get_stock_fundamental

Retrieve fundamental stock data including PER, PBR, and dividend yield for specific KOSPI/KOSDAQ stocks within defined date ranges to analyze financial metrics.

Instructions

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

Args:
    fromdate (str): Start date for retrieval (YYYYMMDD)
    todate   (str): End date for retrieval (YYYYMMDD)
    ticker   (str): Stock ticker symbol

Returns:
    DataFrame:
        >> get_stock_fundamental("20210104", "20210108", "005930")
                          BPS        PER       PBR   EPS       DIV   DPS
            Date
            2021-01-08  37528  28.046875  2.369141  3166  1.589844  1416
            2021-01-07  37528  26.187500  2.210938  3166  1.709961  1416
            2021-01-06  37528  25.953125  2.189453  3166  1.719727  1416
            2021-01-05  37528  26.500000  2.240234  3166  1.690430  1416
            2021-01-04  37528  26.218750  2.210938  3166  1.709961  1416

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fromdate`	Yes
`todate`	Yes
`ticker`	Yes

Implementation Reference

kospi_kosdaq_stock_server.py:304-367 (handler)

The @mcp.tool() decorated handler function implementing the get_stock_fundamental tool. Validates input dates and ticker, fetches data using pykrx's get_market_fundamental_by_date, converts Pandas DataFrame to sorted dictionary with date keys in YYYY-MM-DD format (descending), and handles exceptions.

@mcp.tool()
def get_stock_fundamental(fromdate: Union[str, int], todate: Union[str, int], ticker: Union[str, int]) -> Dict[str, Any]:
    """Retrieves fundamental data (PER/PBR/Dividend Yield) for a specific stock.

    Args:
        fromdate (str): Start date for retrieval (YYYYMMDD)
        todate   (str): End date for retrieval (YYYYMMDD)
        ticker   (str): Stock ticker symbol

    Returns:
        DataFrame:
            >> get_stock_fundamental("20210104", "20210108", "005930")
                              BPS        PER       PBR   EPS       DIV   DPS
                Date
                2021-01-08  37528  28.046875  2.369141  3166  1.589844  1416
                2021-01-07  37528  26.187500  2.210938  3166  1.709961  1416
                2021-01-06  37528  25.953125  2.189453  3166  1.719727  1416
                2021-01-05  37528  26.500000  2.240234  3166  1.690430  1416
                2021-01-04  37528  26.218750  2.210938  3166  1.709961  1416
    """
    # Validate and convert date format
    def validate_date(date_str: Union[str, int]) -> str:
        try:
            if isinstance(date_str, int):
                date_str = str(date_str)
            if '-' in date_str:
                parsed_date = datetime.strptime(date_str, '%Y-%m-%d')
                return parsed_date.strftime('%Y%m%d')
            datetime.strptime(date_str, '%Y%m%d')
            return date_str
        except ValueError:
            raise ValueError(f"Date must be in YYYYMMDD format. Input value: {date_str}")

    def validate_ticker(ticker_str: Union[str, int]) -> str:
        if isinstance(ticker_str, int):
            return str(ticker_str)
        return ticker_str

    try:
        fromdate = validate_date(fromdate)
        todate = validate_date(todate)
        ticker = validate_ticker(ticker)

        logging.debug(f"Retrieving stock fundamental data: {ticker}, {fromdate}-{todate}")

        # Call get_market_fundamental_by_date
        df = get_market_fundamental_by_date(fromdate, todate, ticker)

        # Convert DataFrame to dictionary
        result = df.to_dict(orient='index')

        # Convert datetime index to string and sort in reverse
        sorted_items = sorted(
            ((k.strftime('%Y-%m-%d'), v) for k, v in result.items()),
            reverse=True
        )
        result = dict(sorted_items)

        return result

    except Exception as e:
        error_message = f"Data retrieval failed: {str(e)}"
        logging.error(error_message)
        return {"error": error_message}

kospi_kosdaq_stock_server.py:304-304 (registration)
The @mcp.tool() decorator registers the get_stock_fundamental function as an MCP tool, using the function name as the tool name.
```
@mcp.tool()
```
kospi_kosdaq_stock_server.py:305-305 (schema)
Function signature with type annotations defining the input schema (fromdate, todate, ticker as str or int) and output as Dict[str, Any]. The docstring provides further description and examples.
```
def get_stock_fundamental(fromdate: Union[str, int], todate: Union[str, int], ticker: Union[str, int]) -> Dict[str, Any]:
```

kospi_kosdaq_stock_server.py:7-8 (helper)

Import of get_market_fundamental_by_date from pykrx library, which is the core data retrieval function called by the tool handler.

from pykrx.stock.stock_api import get_market_ohlcv, get_nearest_business_day_in_a_week, get_market_cap, \
    get_market_fundamental_by_date, get_market_trading_volume_by_date, get_index_ohlcv_by_date

kospi-kosdaq