Skip to main content
Glama
kyo504

krx-cli

by kyo504
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

krx-cli

npm version npm downloads license

AI 에이전트를 위한 KRX(한국거래소) Open API CLI & MCP 서버입니다.

Claude Code, GPT, Cursor 등의 AI 에이전트가 Bash tool 또는 MCP를 통해 한국 주식시장 데이터(KOSPI, KOSDAQ, ETF, 채권, 파생상품)를 조회할 수 있습니다.

특징

  • Agent-Native: JSON 출력 기본, 시맨틱 exit code, 스키마 인트로스펙션

  • 전체 시장 커버리지: 지수, 주식, ETF/ETN/ELW, 채권, 파생상품, 일반상품, ESG (31개 엔드포인트)

  • 종목 검색: 종목명으로 검색 후 코드 조회 (krx stock search)

  • 시장 요약: 한 번의 호출로 지수/상승·하락/Top movers 확인 (krx market summary)

  • 워치리스트: 관심 종목 저장 및 일괄 시세 조회 (krx watchlist)

  • 기간 조회: --from/--to로 여러 날짜 데이터 병렬 조회

  • 데이터 파이프라인: --sort, --limit, --code 로 서버 사이드 필터링

  • 파일 캐싱: 과거 데이터 자동 캐싱으로 rate limit 절약

  • 안전한 사용: 입력 검증, rate limit 추적, dry-run 지원

  • 서비스 승인 관리: API별 승인 상태 자동 확인

설치

npm install -g krx-cli
# 또는
pnpm add -g krx-cli
# 또는
yarn global add krx-cli

설정

1. API 키 발급

KRX Open API 포털에서 회원가입 후 API 키를 발급받습니다.

2. API 키 등록

krx auth set <your-api-key>

# 또는 환경변수 사용
export KRX_API_KEY=<your-api-key>

3. 서비스 승인 확인

KRX Open API는 카테고리별로 별도 승인이 필요합니다.

krx auth status
{
  "api_key_set": true,
  "services": {
    "index": { "approved": true },
    "stock": { "approved": true },
    "etp": { "approved": true },
    "bond": { "approved": true },
    "derivative": { "approved": true },
    "commodity": { "approved": true },
    "esg": { "approved": false, "error": "Unauthorized API Call" }
  }
}

사용법

지수 조회

krx index list --date 20260310 --market kospi
krx index list --date 20260310 --market kosdaq

주식 조회

krx stock list --date 20260310 --market kospi
krx stock list --date 20260310 --market kosdaq
krx stock info --market kospi
krx stock search 삼성전자     # 종목 검색

시장 요약

krx market summary                    # 최근 거래일 시장 요약
krx market summary --date 20260310    # 특정 날짜

기간 조회

krx index list --market kospi --from 20260301 --to 20260310
krx stock list --market kospi --from 20260301 --to 20260305 --code KR7005930003

정렬 및 제한

krx stock list --date 20260310 --market kospi --sort FLUC_RT --limit 10
krx stock list --date 20260310 --market kospi --sort ACC_TRDVAL --asc --limit 5

워치리스트

krx watchlist add 삼성전자          # 종목 검색 후 워치리스트 추가
krx watchlist remove 삼성전자       # 정확한 이름으로 제거
krx watchlist remove KR7005930003   # 종목코드로 제거
krx watchlist list                   # 워치리스트 조회
krx watchlist show                   # 워치리스트 종목 시세 조회
krx watchlist show --date 20260310  # 특정 날짜 시세

캐시 관리

krx cache status    # 캐시 현황 조회
krx cache clear     # 캐시 전체 삭제

버전 관리

krx version    # 현재 버전 확인 및 최신 버전 비교
krx update     # 최신 버전으로 업데이트

ETF/ETN/ELW 조회

krx etp list --date 20260310 --type etf
krx etp list --date 20260310 --type etn

채권 조회

krx bond list --date 20260310 --market kts
krx bond list --date 20260310 --market general
krx bond list --date 20260310 --market small

파생상품 조회

krx derivative list --date 20260310 --type futures
krx derivative list --date 20260310 --type options
krx derivative list --date 20260310 --type futures-kospi
krx derivative list --date 20260310 --type futures-kosdaq
krx derivative list --date 20260310 --type options-kospi
krx derivative list --date 20260310 --type options-kosdaq

일반상품 조회

krx commodity list --date 20260310 --type gold
krx commodity list --date 20260310 --type oil
krx commodity list --date 20260310 --type emission

ESG 조회

krx esg list --date 20260310 --type index
krx esg list --date 20260310 --type sri-bond

스키마 조회

krx schema --all
krx schema stock.stk_bydd_trd

글로벌 옵션

옵션

설명

기본값

-o, --output <format>

출력 형식: json, table, ndjson, csv

json (파이프) / table (터미널)

-f, --fields <fields>

출력 필드 필터 (쉼표 구분)

전체

--code <isuCd>

종목코드 필터 (ISU_CD)

-

--sort <field>

결과 정렬 기준 필드

-

--asc

오름차순 정렬 (기본: 내림차순)

-

--offset <n>

처음 N개 건너뛰기 (페이지네이션)

-

--limit <n>

결과 개수 제한

-

--from <date>

기간 조회 시작일 (YYYYMMDD)

-

--to <date>

기간 조회 종료일 (YYYYMMDD)

-

--no-cache

캐시 무시하고 새로 조회

-

--filter <expression>

필터 표현식 (예: "FLUC_RT > 5")

-

--save <path>

결과를 파일로 저장

-

--retries <n>

네트워크 에러 시 재시도 (기본: 3)

-

--dry-run

API 호출 없이 요청 내용 출력

-

-v, --verbose

상세 로그 (stderr)

-

Exit Codes

코드

의미

0

성공

1

일반 오류

2

사용법 오류 (잘못된 인자)

3

데이터 없음

4

인증 실패

5

Rate limit 초과 (일 10,000건)

6

서비스 미승인

AI 에이전트 연동

krx-cli는 AI 에이전트가 Bash tool로 직접 호출하도록 설계되었습니다. 연동은 2단계입니다:

  1. CLI 설치 — 실제 실행 가능한 krx 바이너리

  2. 스킬 설치 — 에이전트에게 사용법을 알려주는 SKILL.md

Step 1: CLI 설치

npm install -g krx-cli
# 또는
pnpm add -g krx-cli
# 또는
yarn global add krx-cli

Step 2: 스킬 설치

skills.sh를 통해 SKILL.md를 에이전트에 등록합니다.

# 모든 에이전트에 글로벌 설치 (권장)
npx skills add kyo504/krx-cli -g

# 특정 에이전트만 지정
npx skills add kyo504/krx-cli -g -a claude-code
npx skills add kyo504/krx-cli -g -a cursor

# 프로젝트 단위 설치 (팀 공유 시)
npx skills add kyo504/krx-cli

Step 3: API 키 설정

krx auth set <your-api-key>
# 또는
export KRX_API_KEY=<your-api-key>

지원 에이전트

skills.sh는 40개 이상의 에이전트를 지원합니다:

에이전트

스킬 설치 경로

Claude Code

~/.claude/skills/

Cursor

~/.cursor/skills/

GitHub Copilot

~/.github-copilot/skills/

Cline

~/.cline/skills/

Windsurf

~/.windsurf/skills/

기타

~/.agents/skills/

사용 예시

스킬 설치 후 에이전트에게 자연어로 요청합니다:

"오늘 코스피 지수 보여줘"
→ krx index list --date 20250311 --market kospi --fields IDX_NM,CLSPRC_IDX,FLUC_RT

"삼성전자 주가 알려줘"
→ krx stock list --date 20250311 --market kospi --fields ISU_NM,TDD_CLSPRC,FLUC_RT -o json

"금 시세 확인해줘"
→ krx commodity list --date 20250311 --type gold

"어떤 API가 승인되어 있어?"
→ krx auth status

스킬 관리

npx skills list -g          # 설치된 스킬 확인
npx skills check             # 업데이트 확인
npx skills update            # 업데이트
npx skills remove krx-cli    # 제거

수동 연동 (skills.sh 없이)

SKILL.md를 직접 에이전트 설정 디렉토리에 복사할 수도 있습니다:

# Claude Code
mkdir -p ~/.claude/skills && cp SKILL.md ~/.claude/skills/krx-cli.md

# Cursor
mkdir -p ~/.cursor/skills && cp SKILL.md ~/.cursor/skills/krx-cli.md

MCP 서버

CLI 외에 MCP(Model Context Protocol) 서버도 제공합니다. 두 가지 전송 방식을 지원합니다:

전송 방식

바이너리

지원 클라이언트

stdio

krx-mcp

Claude Desktop

Streamable HTTP

krx serve

ChatGPT 웹

API 키는 krx auth set <key>로 등록한 것이 자동으로 사용됩니다. krx-mcp는 npm install -g krx-cli로 설치하면 함께 설치됩니다.

Claude Desktop (stdio)

설정 파일 위치:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "krx": {
      "command": "krx-mcp"
    }
  }
}

설정 후 앱을 재시작하면 MCP 도구가 활성화됩니다.

ChatGPT 웹 (Streamable HTTP)

ChatGPT 웹은 원격 MCP 서버만 지원하므로, HTTP 서버를 실행한 뒤 ngrok으로 외부에 노출해야 합니다.

# 터미널 1: MCP 서버 실행
krx serve --port 3000 --host 0.0.0.0

# 터미널 2: ngrok으로 외부 노출
ngrok http 3000

  1. ngrok 출력에서 https://xxxx.ngrok.io URL 복사

  2. ChatGPT 웹 → Settings → Developer → MCP Server 추가

  3. URL: https://xxxx.ngrok.io/mcp

Health check: http://localhost:3000/health

제공 Tool

Tool

설명

krx_index

지수 일별시세 (KOSPI/KOSDAQ/KRX/채권/파생)

krx_stock

주식 일별매매정보 + 종목 기본정보

krx_etp

ETF/ETN/ELW 일별매매정보

krx_bond

채권 일별매매정보 (국채/일반/소액)

krx_derivative

선물/옵션 일별매매정보

krx_commodity

금/석유/배출권 일별매매정보

krx_esg

ESG 지수/채권/ETP 정보

krx_search

종목명 검색 (KOSPI + KOSDAQ)

krx_market_summary

시장 요약 (지수/상승·하락/Top movers/거래량)

krx_watchlist

관심종목 관리 (추가/제거/조회/시세)

krx_schema

엔드포인트 응답 필드 스키마 조회

krx_rate_limit

일일 API 호출 현황 조회

제공 Resource

MCP Resource로 읽기 전용 상태 데이터를 노출합니다.

Resource

설명

krx://watchlist

워치리스트 종목 목록 (JSON)

krx://rate-limit

일일 API 호출 현황 (JSON)

krx://service-status

카테고리별 서비스 승인 상태 (JSON)

활용 가이드

AI 에이전트와 함께 할 수 있는 다양한 활용 사례는 에이전트 활용 가이드를 참고하세요. 포트폴리오 모니터링, 시장 분석 리포트, 종목 스크리닝, 백테스트 등 11가지 구체적인 시나리오를 소개합니다.

사용 예시

MCP 클라이언트에서 자연어로 요청하면 됩니다:

"오늘 코스피 지수 보여줘"
→ krx_index tool 호출 (endpoint: "kospi_dd_trd")

"삼성전자 주가 알려줘"
→ krx_stock tool 호출 (endpoint: "stk_bydd_trd", fields: ["ISU_NM", "TDD_CLSPRC", "FLUC_RT"])

"오늘 API 몇 번 호출했어?"
→ krx_rate_limit tool 호출

개발

pnpm install
pnpm build
pnpm test
pnpm test:e2e
pnpm typecheck
pnpm lint

라이선스

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
11Releases (12mo)

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kyo504/krx-cli'

If you have feedback or need assistance with the MCP directory API, please join our Discord server