Ko Stock

ko-stock-mcp

An MCP server that exposes Korean DART (전자공시시스템, Financial Supervisory Service electronic disclosure) data to MCP clients such as Claude Desktop.

한국어 문서는 README.ko.md를 참고하세요.

Tools

Both DART (electronic disclosure) and KRX (Korea Exchange) tools are provided.

DART (disclosure)

Tool	Description
get_corp_code	Look up a company's DART corp_code (8-digit) by name or stock code (6-digit). Entry point for the other tools.
get_company_info	Company profile (name, CEO, market class, industry, incorporation date, etc.).
get_disclosure_list	Search disclosures by company / date range / disclosure type.
get_disclosure	Fetch a disclosure's original document. Large docs return a table of contents (toc); drill in with section_id.
get_financial_statement	XBRL financial statements (BS / IS / CIS / SCE / CF) from periodic reports.
get_today_date	Today's date in KST/UTC (YYYYMMDD + ISO).

KRX (Korea Exchange) — requires KRX_API_KEY

Tool	Description
get_market_type	Determine which market (KOSPI/KOSDAQ/KONEX) a stock code belongs to. Uses DART corp class first, falls back to KRX.
get_stock_trade_info	Daily trading data for a business day (close, change rate, volume, market cap, etc.).
get_stock_base_info	Stock base info (name, standard/short code, listing date, par value, shares outstanding, etc.).

Typical flow — disclosures/financials: get_corp_code → (get_disclosure_list | get_financial_statement | get_company_info) → get_disclosure for full text. Market data: (optionally get_market_type →) get_stock_trade_info | get_stock_base_info (bas_dd must be a business day; non-trading days return empty).

KRX tools return a friendly error when KRX_API_KEY is unset; DART features are unaffected. Note get_market_type works with just the DART key (via corp class).

KRX response fields

get_stock_trade_info / get_stock_base_info return the raw KRX fields verbatim under result (amounts/quantities are strings, dates are YYYYMMDD).

get_stock_trade_info (daily trading data)

Field	Meaning
BAS_DD	Base date (YYYYMMDD)
ISU_CD	Stock code (6-digit short code in this response)
ISU_NM	Stock name
MKT_NM	Market (KOSPI/KOSDAQ/KONEX)
SECT_TP_NM	Section/board
TDD_CLSPRC	Closing price
CMPPREVDD_PRC	Change vs. previous day
FLUC_RT	Change rate (%)
TDD_OPNPRC / TDD_HGPRC / TDD_LWPRC	Open / High / Low
ACC_TRDVOL	Accumulated trading volume (shares)
ACC_TRDVAL	Accumulated trading value (KRW)
MKTCAP	Market capitalization (KRW)
LIST_SHRS	Listed shares

get_stock_base_info (stock base info)

Field	Meaning
ISU_CD	Standard code (12-digit, e.g. KR7005930003)
ISU_SRT_CD	Short code (6-digit, e.g. 005930)
ISU_NM	Full stock name
ISU_ABBRV	Abbreviated name
ISU_ENG_NM	English name
LIST_DD	Listing date (YYYYMMDD)
MKT_TP_NM	Market (KOSPI/KOSDAQ/KONEX)
SECUGRP_NM	Security group (e.g. common stock)
SECT_TP_NM	Section/board
KIND_STKCERT_TP_NM	Share type (e.g. ordinary)
PARVAL	Par value
LIST_SHRS	Listed shares

get_market_type returns { "market": "KOSPI"|"KOSDAQ"|"KONEX", "source": "dart"|"krx"|"cache" } (source is where the classification came from).

Requirements

• Python >= 3.10
• uv
• A DART Open API key — sign up at https://opendart.fss.or.kr (free, instant).
• (Optional) A KRX Open API key — sign up at https://openapi.krx.co.kr, request a key, then apply for the six stock services (3 daily-trade + 3 base-info); approval takes ~1 day. Only needed for the KRX market-data tools.

Setup

uv sync
cp .env.example .env   # then put your DART_API_KEY in .env

Run / develop

# Launch the MCP Inspector for local testing
uv run mcp dev src/ko_stock_mcp/server.py

# Or run the server directly (stdio)
uv run ko-stock-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ko-stock-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ko-stock-mcp", "run", "python", "-m", "ko_stock_mcp.server"]
    }
  }
}

uv --directory runs the server with this project as the working directory, so .env (with DART_API_KEY, and optionally KRX_API_KEY) is loaded automatically — no need to duplicate the keys here. If you prefer, you can instead pass them explicitly:

"env": { "DART_API_KEY": "<YOUR_DART_API_KEY>", "KRX_API_KEY": "<YOUR_KRX_API_KEY>" }

On macOS the config lives at ~/Library/Application Support/Claude/claude_desktop_config.json. Restart Claude Desktop after editing.

License

MIT — see LICENSE.