Pykrx MCP

🚀 pykrx-mcp

A MCP (Model Context Protocol) server that provides South Korean stock market data to AI agents.

This server is based on the pykrx library, enabling natural - language queries of various data, such as stock prices, financial statements, investor supply - demand, and short - selling data from the KOSPI, KOSDAQ, and KONEX markets, on ChatGPT and Claude.

☕ Support the Project

If this project has been helpful to you, please support the developer!

🚀 Quick Start

Use in Claude Desktop

Automatic Installation (Recommended)

One - click installation via MCP Registry:

npx @modelcontextprotocol/inspector install pykrx-mcp

Manual Installation

Manually modify the Claude Desktop configuration file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pykrx": {
      "command": "uvx",
      "args": ["pykrx-mcp"]
    }
  }
}

After the configuration, restart Claude Desktop to use it immediately.

✨ Features

Supported Data and APIs

All APIs are implemented based on the pykrx library.

Stock Data

Ticker Information

• get_market_ticker_list: Query ticker codes by market.
• get_market_ticker_name: Query the stock name by ticker code.

Price Data

• get_stock_ohlcv: Get OHLCV (Open/High/Low/Close/Volume) data for individual stocks.
• get_market_ohlcv_by_date: Get the market quotes of all stocks on a specific date.
• get_market_price_change: Get the price changes of all stocks over a period.

Market Capitalization

• get_market_cap_by_date: Query the market capitalization of individual stocks.

Financial Indicators

• get_market_fundamental_by_date: Get PER, PBR, EPS, DIV, BPS, DPS.

Investor - Specific Trading

• get_market_trading_value_by_date: Get the investor supply - demand (trading value) for each stock.
• get_market_trading_volume_by_investor: Get the trading volume by investor type.
• get_market_trading_value_by_investor: Get the trading value by investor type.
• get_market_net_purchases_of_equities: Get the top stocks with net purchases by investors.

Index Data

Index Information

• get_index_ticker_list: Get the list of index tickers.
• get_index_ticker_name: Query the index name.
• get_index_portfolio_deposit_file: Get the constituent stocks of an index.

Index Price

• get_index_ohlcv: Get the OHLCV data of an index.

Index Indicators

• get_index_fundamental: Get the PER/PBR/dividend yield of an index.

Short Selling Data

• get_shorting_status_by_date: Get the short - selling status of each stock.
• get_shorting_volume_by_ticker: Get the short - selling trading volume of all stocks.
• get_shorting_balance_top50: Get the top 50 stocks with the highest short - selling balance.
• get_shorting_volume_top50: Get the top 50 stocks with the highest short - selling trading ratio.

Foreign Investment

• get_exhaustion_rates_of_foreign_investment: Get the foreign ownership and limit exhaustion rate.

ETF Data

• get_etf_ticker_list: Get the list of ETF tickers.
• get_etf_ohlcv_by_date: Get the OHLCV data of ETFs.

A total of 23 data query tools are supported.

💻 Usage Examples

Stock Price Query

Individual Stock Price

"Show me the stock price of Samsung Electronics in the last month."
"Get the OHLCV data of SK Hynix in January 2024."
"Analyze the stock price movement of Kakao last week."

Market - Wide Quotes

"Show me the quotes of all KOSPI stocks today."
"Get the price change rates of the top 10 KOSDAQ stocks."

Market Capitalization & Trading Volume

"What is the market capitalization of Samsung Electronics?"
"Show me the trading volume trend of Samsung Electronics in the last month."
"Analyze the trading value of Naver."

Financial Indicators

"Tell me the PER and PBR of Samsung Electronics."
"What is the dividend yield of Samsung Electronics?"
"What is the recent EPS of Naver?"

Investor - Specific Supply - Demand Analysis

"How is the foreign buying pressure on Samsung Electronics?"
"Analyze the institutional supply - demand of Kakao recently."
"Which KOSPI stocks are bought by individual investors?"
"Show me the top 10 stocks with net purchases by foreigners."

Short - Selling Analysis

"What is the short - selling ratio of Samsung Electronics?"
"Tell me the top short - selling stocks in KOSPI."
"Which stock has the highest short - selling balance?"

Index Query

"Show me the trend of the KOSPI index in the last month."
"What is the PER of the KOSDAQ 150 index?"
"Tell me the constituent stocks of the semiconductor sector index."

Foreign Investment

"What is the foreign ownership ratio of Samsung Electronics?"
"Show me the stocks with a high foreign limit exhaustion rate."

Stock Search

"Show me the list of KOSPI stocks."
"What is the name of the stock with ticker 005930?"
"Show me the list of ETFs traded today."

✨ Key Features

Natural - Language Conversational Interface

You can query data in everyday language without complex API syntax.

Real - Time South Korean Stock Market Data

It provides the latest data from the KRX (Korea Exchange).

Diverse Analysis Functions

• Price trend analysis
• Investor - specific supply - demand analysis
• Financial indicator comparison
• Short - selling status analysis

AI Agent Optimization

It supports the MCP protocol for direct use on ChatGPT and Claude.

🔧 Technical Details

• Python 3.10+
• pykrx: Collect South Korean stock market data.
• FastMCP: MCP server framework.
• MCP (Model Context Protocol): Communication protocol with AI agents.

🛠️ Developer Information

Local Development Environment Setup

For detailed information, please refer to DEVELOPMENT.md.

# Clone the repository
git clone https://github.com/sharebook-kr/pykrx-mcp.git
cd pykrx-mcp

# Install dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Start the server
uv run pykrx-mcp

Contributing

Issues and pull requests are welcome!

📄 License

MIT License - Use it freely!

🔗 Related Projects

• pykrx: A library for collecting South Korean stock market data (the basis of this project).
• MCP: Official documentation of the Model Context Protocol.