Korea KRX MCP

KRX(한국거래소) Open API를 데이터 파이프 MCP 서버로 제공합니다. 지수·주식·ETP·채권·파생·일반상품 시세를 LLM이 직접 읽을 수 있도록 전달합니다. 분석·가공·판단은 MCP가 하지 않고 LLM이 원시 레코드를 읽고 수행합니다.

Tools

| Tool | 카테고리 | 흡수 엔드포인트 | |---|---|---| | get_index_daily | 지수 (idx) | 5 (KRX·KOSPI·KOSDAQ·BOND·DERIVATIVE) | | get_stock_daily | 주식 매매 (sto) | 5 (KOSPI·KOSDAQ·KONEX·WARRANT·SUBSCRIPTION_RIGHT) | | get_stock_base_info | 주식 기본정보 (sto) | 3 (KOSPI·KOSDAQ·KONEX) | | get_etp_daily | ETP (etp) | 3 (ETF·ETN·ELW) | | get_bond_daily | 채권 (bon) | 3 (KTS·GENERAL·SMALL) | | get_derivatives_daily | 파생 (drv) | 6 (FUTURES·STOCK_FUTURES_KOSPI/KOSDAQ·OPTIONS·STOCK_OPTIONS_KOSPI/KOSDAQ) | | get_commodity_daily | 일반상품 (gen) | 3 (OIL·GOLD·EMISSIONS) | | find_stock | 종목코드 리졸버 | 종목명/코드 → 후보 목록 (base_info 기반) |

28개 KRX 엔드포인트를 7개 시세 도구로 압축 + 종목코드 리졸버 1개 = 8개. ESG 카테고리는 범위 제외.

Design

• basDd(YYYYMMDD) 하나로 해당일 전체 시장 데이터를 반환합니다. 생략 시 직전 영업일(평일) 자동 사용.
• 날짜 범위 조회: 시세 도구에 endDd(선택)를 주면 basDd~endDd 영업일을 순회 조회합니다(주말 자동 스킵, 미캐시 최대 10영업일, 날짜 폭 최대 62일). 각 레코드에 BAS_DD가 내장된 평탄 배열 + 메타(tradingDays/skippedDays/cacheHits/downloads/failedDays)를 반환합니다. endDd 미지정 시 단일일 동작은 기존과 동일합니다.
• 과거일 캐시: 과거 확정일(오늘 이전 & 비어있지 않은 응답)의 시세는 디스크에 캐시해 재조회를 즉시 처리합니다(불변 데이터). 당일·휴장일(빈 배열)은 캐시하지 않습니다. 캐시 경로는 KRX_CACHE_DIR(기본 ~/.korea-krx-mcp/cache/)입니다.
• 신뢰성: 요청 타임아웃 15초, 실패 시 1회 재시도(타임아웃·5xx·네트워크 오류에 한함). 에러는 원인별로 구분된 메시지를 반환합니다.
• 종목 필터·검색: 개별 종목은 codeList(6자리 단축코드)로 클라이언트 측 필터링합니다. 종목명→코드 변환은 find_stock으로 후보를 찾아 isuSrtCd를 codeList에 넘기는 2단계 흐름입니다.

Install

npm install
npm run build

Run

KRX_API_KEY가 필요합니다. KRX 정보데이터시스템에서 Open API 인증키를 신청하세요.

$env:KRX_API_KEY="YOUR_KRX_API_KEY"
npm start

MCP 클라이언트에서는 build/index.js를 stdio 서버로 등록하세요.

Environment

| 변수 | 필수 | 설명 | |---|---|---| | KRX_API_KEY | ✅ | KRX Open API 인증키 (AUTH_KEY 헤더) | | KRX_CACHE_DIR | | 과거일 시세·종목 마스터 캐시 경로 (기본 ~/.korea-krx-mcp/cache/) |

카테고리별 API 이용신청: KRX Open API는 카테고리(지수·주식·ETP·채권·파생·일반상품)별로 이용신청이 필요할 수 있습니다. 미승인 카테고리는 401을 반환합니다.

Notes

• KRX Open API key: https://data.krx.co.kr
• Base URL: https://data-dbg.krx.co.kr/svc/apis
• 인증 방식: AUTH_KEY 헤더
• 응답 형식: { "OutBlock_1": [ { 필드: "값", ... } ] } (모든 값 문자열)