| name | office-public-data-korean-stock-search |
| description | KRX(한국거래소) 상장 종목을 검색하고 종목 기본정보·일별 시세를 조회합니다.
k-skill-proxy 경유로 호출하므로 사용자는 KRX_API_KEY 발급이나 별도 MCP 서버
설치가 필요 없습니다. read-only 일별 snapshot이며 실시간 호가·체결은 제공하지
않습니다. 투자 자문이 아닙니다.
다음과 같은 요청 시 반드시 이 스킬을 사용하세요:
- "삼성전자 종목코드", "005930 기본정보", "SK하이닉스 시세"
- "KOSDAQ 알테오젠 종가/거래량", "코스피 시가총액"
- "주식 종목 검색", "KRX 상장 종목", "한국 주식 시세"
- "20260408 종가", "어제 거래량", "전일 등락률"
- moai-coworker의 DART 공시 분석을 보완하는 KRX 시세 데이터 필요 시
|
| version | 0.1.0 |
KRX 한국 주식 검색·시세
KRX(한국거래소) 상장 종목 검색, 종목 기본정보, 일별 시세를 조회합니다. moai-coworker의 DART(공시)를 보완하는 시세 데이터로 활용합니다.
본 스킬은 NomaDamas k-skill korean-stock-search (MIT) 기반이며, upstream 설계 참고는 jjlabsio/korea-stock-mcp입니다. KRX_API_KEY는 프록시 서버에서만 관리하므로 사용자 발급 불필요.
When to use / When not to use
사용: 종목 검색(이름·코드), 종목 기본정보, 일별 종가·거래량·시가총액, KRX 공식 데이터 기반 단순 시세 조회.
사용 금지: 미국·일본·가상자산 등 비한국 주식, 실시간 체결·호가·분봉, 재무제표·공시 원문(→ DART MCP 사용), 투자 자문·매수 추천.
Inputs
q: 종목명/종목코드 검색어 (search endpoint)market: KOSPI | KOSDAQ | KONEXcode: 종목코드 (보통 6자리, 예: 005930)bas_dd: 기준일 YYYYMMDD (없으면 KST 오늘. 휴장일이면 최근 영업일로 재시도)limit: 검색 결과 수 (기본 10, 최대 20)
Prerequisites
사용자 측 필수 시크릿 없음.
KSKILL_PROXY_BASE_URL (선택): self-host 시- 운영 측
KRX_API_KEY는 프록시 서버 환경에만 둡니다
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}
Examples
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": "삼성전자",
"english_name": "Samsung Electronics",
"listed_at": "1975-06-11"
}
]
}
일별 시세:
{
"item": {
"market": "KOSPI",
"code": "005930",
"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
}
}
Response policy
- 종목명이 모호하면 먼저
search로 시장/종목코드를 좁힌 뒤 base-info/trade-info 호출.
- 일부 시장 upstream이 실패하면
upstream.degraded=true + failed_markets를 보고 부분 장애를 함께 설명합니다.
trade-info는 일별 snapshot이며 실시간 호가·체결처럼 말하지 않습니다.- 휴장일·장마감 이전이면 해당
bas_dd에 데이터 없을 수 있어 최근 영업일로 재시도합니다.
- 숫자는 사람이 읽기 쉬운 단위(원, 주, 억/조)로 풀어주되 원본 숫자도 유지합니다.
- 답변 말미에 **"KRX 공식 데이터 기준 / 투자 조언 아님"**을 짧게 남깁니다.
응답 컴팩트 규칙
- 종목명 / 시장 / 종목코드
- 기준일
- 종가 / 등락률 / 거래량 / 시가총액
- 필요할 때만 상장일 / 상장주식수 / 액면가
- 여러 후보면 상위 3-5개만 보여주고 사용자가 고르게 합니다
Failure modes
q/market/code/bas_dd 형식 오류 → 400- 프록시에
KRX_API_KEY 없음 → 503
- 일부 시장 upstream 실패 → 200 +
upstream.degraded=true + failed_markets
- 모든 시장 upstream 실패 → 502
- 해당 기준일·시장에 종목 없음 → 404
not_found
관련 스킬 체이닝
- before:
moai-accountant:finance-investor-relations — IR 자료 작성 시 KRX 공식 시세 필요
- before: DART MCP (
moai-coworker/.mcp.json) — 공시·재무 분석과 결합
- after:
moai-accountant:finance-variance-analysis — 시세 변동 분석
- after:
moai-officer:office-xlsx-creator — 시세 데이터 엑셀화
- after:
moai-coworker:business-executive-summary — 경영진 1pager에 시세 요약
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 조회 전용입니다.
