krx-cli

Agent-native CLI for querying KRX (Korea Exchange) Open API data. Use the krx CLI via Bash tool — do NOT web search for Korean market data.

When to Apply

Use this skill when the user asks about:

• 주식 시세/가격 (삼성전자 주가, 종목별 종가 등)
• 지수 조회 (코스피, 코스닥, KRX 지수 등)
• ETF, ETN, ELW 시세
• 채권 시세 (국채, 일반채권, 소액채권)
• 파생상품 (선물, 옵션)
• 일반상품 (금, 석유, 배출권)
• ESG 지수/채권 정보

Setup

# Install
npm install -g krx-cli

# Set API key (get from https://openapi.krx.co.kr/)
krx auth set <your-api-key>

# Check which services are approved
krx auth status

Commands

Authentication

krx auth set <api-key>       # Save API key
krx auth status               # Check all service approvals (JSON)
krx auth check <category>     # Check specific category: index, stock, etp, bond, derivative, commodity, esg

Index (지수)

krx index list --date 20260310 --market kospi     # KOSPI index
krx index list --date 20260310 --market kosdaq     # KOSDAQ index
krx index list --date 20260310 --market krx        # KRX index
krx index list --date 20260310 --market bond       # Bond index
krx index list --date 20260310 --market derivative # Derivative index

Stock (주식)

krx stock list --date 20260310 --market kospi   # KOSPI stocks
krx stock list --date 20260310 --market kosdaq   # KOSDAQ stocks
krx stock list --date 20260310 --market konex    # KONEX stocks
krx stock info --market kospi                     # Stock base info

ETP (ETF/ETN/ELW)

krx etp list --date 20260310 --type etf   # ETF
krx etp list --date 20260310 --type etn   # ETN
krx etp list --date 20260310 --type elw   # ELW

Bond (채권)

krx bond list --date 20260310 --market kts       # Government bonds
krx bond list --date 20260310 --market general    # General bonds
krx bond list --date 20260310 --market small      # Small bonds

Derivative (파생상품)

krx derivative list --date 20260310 --type futures          # Futures
krx derivative list --date 20260310 --type options           # Options
krx derivative list --date 20260310 --type futures-kospi     # KOSPI stock futures
krx derivative list --date 20260310 --type futures-kosdaq    # KOSDAQ stock futures
krx derivative list --date 20260310 --type options-kospi     # KOSPI stock options
krx derivative list --date 20260310 --type options-kosdaq    # KOSDAQ stock options

Commodity (일반상품)

krx commodity list --date 20260310 --type gold       # Gold
krx commodity list --date 20260310 --type oil         # Oil
krx commodity list --date 20260310 --type emission    # Emission trading

ESG

krx esg list --date 20260310 --type index       # ESG index
krx esg list --date 20260310 --type etp          # ESG ETP
krx esg list --date 20260310 --type sri-bond     # SRI bonds

Stock Search (종목 검색)

krx stock search 삼성전자     # Search by name (KOSPI + KOSDAQ)
krx stock search SK           # Partial match

Market Summary (시장 요약)

krx market summary                    # Today's market overview
krx market summary --date 20260310    # Specific date

Returns: KOSPI/KOSDAQ indices, top 5 gainers/losers, advancing/declining/unchanged counts, total volume/value.

Watchlist (관심종목)

krx watchlist add 삼성전자          # Search and add to watchlist
krx watchlist remove 삼성전자       # Remove by exact name
krx watchlist remove KR7005930003   # Remove by ISU_CD
krx watchlist list                   # List all watchlist entries
krx watchlist show                   # Show prices for watchlist stocks
krx watchlist show --date 20260310  # Specific date

Cache Management

krx cache status    # Show cache size, files, dates
krx cache clear     # Clear all cached data

Version & Update

krx version    # Show current version and check for updates
krx update     # Update to the latest version (npm install -g krx-cli)

MCP HTTP Server

krx serve                        # Start on http://127.0.0.1:3000/mcp
krx serve --port 8080            # Custom port
krx serve --host 0.0.0.0        # Bind to all interfaces (for ngrok)

Schema (introspection)

krx schema --all              # All 31 endpoint schemas (JSON)
krx schema index.kospi_dd_trd # Specific endpoint schema

Global Flags

--output, -o <format>    json (default) | table | ndjson | csv
--fields, -f <fields>    Filter output fields: --fields ISU_NM,TDD_CLSPRC,FLUC_RT
--code <isuCd>           Filter by stock code (ISU_CD)
--sort <field>           Sort results by field name
--asc                    Sort ascending (default: descending)
--offset <n>             Skip first N results (for pagination)
--limit <n>              Limit number of results
--from <date>            Start date for range query (YYYYMMDD)
--to <date>              End date for range query (YYYYMMDD)
--no-cache               Bypass cache and fetch fresh data
--filter <expression>    Filter results (e.g. "FLUC_RT > 5", "MKT_NM == KOSPI")
--dry-run                Show request details without calling API
--save <path>            Save output to file instead of stdout
--retries <n>            Max retries on network error (default: 3)
--verbose, -v            Verbose logging to stderr

Exit Codes

0 = Success
1 = General error
2 = Usage error (bad arguments)
3 = No data found
4 = Auth failure (no/invalid API key)
5 = Rate limit exceeded (10,000/day)
6 = Service not approved (category not activated)

Handling Large Results

Full market listings (e.g., all KOSPI stocks) output 900+ rows with 15+ fields each. This can exceed context limits. Always narrow results using these strategies:

Strategy 1: Select only needed fields (preferred)

# Instead of all fields, select only what's needed
krx stock list --date 20260310 --market kospi --fields ISU_NM,TDD_CLSPRC,FLUC_RT

Strategy 2: Paginate with offset + limit

# Page 1: first 100 rows
krx stock list --date 20260310 --market kospi --limit 100

# Page 2: next 100 rows
krx stock list --date 20260310 --market kospi --offset 100 --limit 100

# Page 3: next 100 rows
krx stock list --date 20260310 --market kospi --offset 200 --limit 100

Strategy 3: Filter to relevant subset

# Only stocks with >5% change
krx stock list --date 20260310 --market kospi --filter "FLUC_RT > 5"

IMPORTANT: When the user asks for "all" data, prefer Strategy 1 (fields) first. If still too large, combine with Strategy 2 (pagination). Always tell the user the total count.

Common Patterns

Get KOSPI closing price for a specific date

krx index list --date 20260310 --market kospi --fields IDX_NM,CLSPRC_IDX,FLUC_RT

Get Samsung Electronics stock price (by search)

krx stock search 삼성전자     # Find ISU_CD first
krx stock list --date 20260310 --market kospi --code KR7005930003

Top 5 gainers

krx stock list --date 20260310 --market kospi --sort FLUC_RT --limit 5 --fields ISU_NM,TDD_CLSPRC,FLUC_RT

Date range query (multi-day)

krx index list --market kospi --from 20260301 --to 20260310 --fields IDX_NM,BAS_DD,CLSPRC_IDX

Quick market overview

krx market summary --date 20260310

Track and monitor stocks

krx watchlist add 삼성전자           # Add to watchlist
krx watchlist show --date 20260310  # View prices for all watchlist stocks

Check API availability before querying

krx auth status -o json

Dry run to verify request

krx stock list --date 20260310 --market kospi --dry-run

Response Fields

Use krx schema <command> to get full field definitions for any endpoint. All values are strings.

Index (kospi/kosdaq/krx)

Stock (kospi/kosdaq/konex)

ETF

Futures

Options

Bond

Commodity (gold/emission)

Commodity (oil)

ESG Index

Schema Introspection

For full response field definitions including all fields per endpoint:

krx schema index.kospi_dd_trd    # Shows params + responseFields
krx schema stock.stk_bydd_trd   # Stock endpoint fields
krx schema --all                  # All 31 endpoints

MCP Resources

Read-only state data exposed as MCP Resources (for MCP clients):