Home

Skill

API Development

korean-stock-search

nomadamas/k-skill

Use k-skill-proxy to search Korean listed stocks, inspect KRX base information, and fetch daily trade snapshots without asking the user to issue a KRX API key.

...Expand all

Updated time July 8, 2026

# API Development # api-integration # korean-stocks # data-retrieval # stock-market # finance

About korean-stock-search

The korean-stock-search skill provides a convenient interface for accessing information on Korean listed stocks without requiring users to manage their own KRX API key or set up a local server. It leverages a proxy server to handle requests to the KRX system, allowing users to search for listed stocks, retrieve base information, and fetch daily trading data. This skill solves the problem of cumbersome API key management and direct integration with KRX endpoints, simplifying stock data retrieval for developers, analysts, and finance enthusiasts working with Korean markets.

The skill supports three main endpoints: stock search, base information, and daily trade information. Users can search for stocks by name or code, retrieve detailed information such as market type, stock certificate type, and number of listed shares, and access daily trading data including open, high, low, and close prices, trading volume, trading value, and market capitalization. The skill automatically handles defaults for dates and market selection, ensuring smooth queries even on holidays or when certain data points are missing. Requests can be made via simple HTTP calls to the proxy server, with optional environment configuration for the proxy base URL.

This skill is ideal for developers building finance applications, analysts tracking Korean stock performance, or educational projects exploring stock market data. Common use cases include looking up stock codes, obtaining detailed stock information, and fetching daily market snapshots for specific dates or stocks. It is specifically designed for Korean equities and does not support foreign stocks, real-time order book data, or financial advisory services, making it suitable for read-only data retrieval in research and analysis contexts.

FAQ

Do I need a KRX API key to use this skill?

No, the skill uses a proxy server to manage the KRX API key, so users do not need to obtain their own key.

Which stock markets are supported?

The skill supports KOSPI, KOSDAQ, and KONEX markets in Korea.

Can I get real-time trading or minute-level data?

No, this skill only provides daily trade snapshots and base information; it does not support real-time or intraday data.

What should I do if I search for a stock and get multiple results?

You should first use the search endpoint to narrow down the stock code and market, then use the base-info or trade-info endpoints for detailed data.

Can I use this skill for foreign stocks or cryptocurrencies?

No, the skill is limited to Korean listed stocks and does not support foreign equities or digital assets.

View on GitHub

Korean Stock Search

What this skill does

기본적으로 https://k-skill-proxy.nomadamas.org/v1/korean-stock/... 로 요청해서 KRX 상장 종목 검색, 종목 기본정보, 일별 시세를 조회한다.

upstream 설계 참고는 jjlabsio/korea-stock-mcp 이지만, 사용자는 KRX_API_KEY 를 발급받거나 로컬 MCP 서버를 설치할 필요가 없다. KRX_API_KEY 는 proxy 서버에서만 관리한다.

When to use

"삼성전자 종목코드랑 시장구분 찾아줘"
"005930 기본정보 보여줘"
"SK하이닉스 20260408 종가/거래량 알려줘"
"KOSDAQ 에서 알테오젠 시세 확인해줘"

When not to use

미국/일본/가상자산 같은 비한국 주식 조회
실시간 체결/호가/분봉 조회
재무제표/공시 원문 분석 (이 스킬 범위 밖)
투자 자문/매수 추천

Inputs

q: 종목명 또는 종목코드 검색어 (search endpoint)
market: KOSPI | KOSDAQ | KONEX
code: 종목코드 (보통 6자리 단축코드, 예: 005930)
bas_dd: 기준일 YYYYMMDD (없으면 KST 오늘 날짜 기본값, 휴장일이면 최근 영업일로 다시 시도)
limit: 검색 결과 수 (기본 10, 최대 20)

Prerequisites

없음. 사용자는 KRX_API_KEY 를 준비할 필요가 없다. upstream key는 proxy 서버에서만 주입한다.

Default path

추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.

KSKILL_PROXY_BASE_URL 환경변수가 있으면 그 값을 사용하고, 없으면 기본 경로 https://k-skill-proxy.nomadamas.org 를 사용한다.

Supported endpoints

종목 검색

GET /v1/korean-stock/search?q={검색어}&bas_dd={YYYYMMDD}

종목 기본정보

GET /v1/korean-stock/base-info?market={KOSPI|KOSDAQ|KONEX}&code={종목코드}&bas_dd={YYYYMMDD}

종목 일별 시세

GET /v1/korean-stock/trade-info?market={KOSPI|KOSDAQ|KONEX}&code={종목코드}&bas_dd={YYYYMMDD}

Example requests

종목 검색:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/search' \  --data-urlencode 'q=삼성전자' \  --data-urlencode 'bas_dd=20260408'

종목 기본정보:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/base-info' \  --data-urlencode 'market=KOSPI' \  --data-urlencode 'code=005930' \  --data-urlencode 'bas_dd=20260408'

종목 일별 시세:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/trade-info' \  --data-urlencode 'market=KOSPI' \  --data-urlencode 'code=005930' \  --data-urlencode 'bas_dd=20260408'

Response shape

검색 응답

{  "items": [    {      "market": "KOSPI",      "code": "005930",      "standard_code": "KR7005930003",      "name": "삼성전자",      "short_name": "삼성전자",      "english_name": "Samsung Electronics",      "listed_at": "1975-06-11"    }  ],  "query": { "q": "삼성전자", "bas_dd": "20260408", "limit": 10 },  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }}

기본정보 응답

{  "item": {    "market": "KOSPI",    "code": "005930",    "standard_code": "KR7005930003",    "name": "삼성전자",    "short_name": "삼성전자",    "english_name": "Samsung Electronics",    "security_group": "주권",    "section_type": "대형주",    "stock_certificate_type": "보통주",    "par_value": 100,    "listed_shares": 5969782550  },  "query": { "market": "KOSPI", "code": "005930", "bas_dd": "20260408" },  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }}

일별 시세 응답

{  "item": {    "market": "KOSPI",    "code": "005930",    "standard_code": "KR7005930003",    "base_date": "20260408",    "name": "삼성전자",    "close_price": 84000,    "change_price": 1000,    "fluctuation_rate": 1.2,    "open_price": 83000,    "high_price": 84500,    "low_price": 82800,    "trading_volume": 12345678,    "trading_value": 1030000000000,    "market_cap": 500000000000000  },  "query": { "market": "KOSPI", "code": "005930", "bas_dd": "20260408" },  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }}

Response policy

종목명이 모호하면 먼저 search 로 시장/종목코드를 좁힌 뒤 base-info 또는 trade-info 로 들어간다.
일부 시장 upstream 이 실패하면 upstream.degraded=true 와 failed_markets 를 보고 부분 장애 여부를 함께 설명한다.
trade-info 결과는 일별 snapshot 이다. 실시간 호가/체결처럼 말하지 않는다.
휴장일/장마감 이전이면 해당 bas_dd 에 데이터가 없을 수 있으니 최근 영업일로 재시도한다. 이 경우 trade-info 는 502 대신 not_found 로 끝날 수 있다.
숫자는 사람이 읽기 쉬운 단위(원, 주, 억/조)로 짧게 풀어주되 원본 숫자도 유지한다.
답변 말미에 "KRX 공식 데이터 기준 / 투자 조언 아님" 을 짧게 남긴다.

Keep the answer compact

종목명 / 시장 / 종목코드
기준일
종가 / 등락률 / 거래량 / 시가총액
필요할 때만 상장일 / 상장주식수 / 액면가
여러 후보가 나오면 상위 3~5개만 보여주고 사용자가 고르게 한다

Failure modes

q, market, code, bas_dd 형식이 잘못되면 400 응답
프록시 서버에 KRX_API_KEY 가 없으면 503 응답
검색 중 일부 시장 upstream 이 실패하면 200 응답이지만 upstream.degraded=true 와 failed_markets 를 함께 반환할 수 있다.
모든 요청 시장에서 upstream KRX 조회가 실패하면 502 응답
해당 기준일/시장에 종목이 없으면 404 not_found

Done when

검색어가 모호하면 search 로 후보를 먼저 좁혔다.
필요한 경우 base-info 와 trade-info 를 호출해 핵심 수치를 정리했다.
사용자가 KRX_API_KEY 없이도 조회 가능하다는 점을 유지했다.
KRX 공식 데이터 기준임을 짧게 남겼다.

Notes

원본 참고: https://github.com/jjlabsio/korea-stock-mcp
공식 데이터 출처: KRX Open API (https://openapi.krx.co.kr/contents/OPP/MAIN/main/index.cmd)
이 스킬은 read-only 조회 전용이다.