kiwoom-mcp-server 0.9.0 → 0.12.0

package/README.en.md

@@ -25,13 +25,16 @@ allowance.
 |---|---|---|
 | `search_stock` | Name → code search (KOSPI/KOSDAQ, incl. ETF/ETN) | ka10099 |
 | `get_stock_price` | Current price / change rate / volume / basic metrics | ka10001 |
-| `get_stock_chart` | Daily/weekly/monthly/minute candles (adjusted price) | ka10080~83 |
+| `get_stock_chart` | Daily/weekly/monthly/yearly/minute/tick candles (adjusted price) | ka10079~83, ka10094 |
 | `get_orderbook` | 10-level ask/bid quotes and sizes | ka10004 |
 | `get_market_index` | KOSPI/KOSDAQ composite and sector indices | ka20003 |
+| `get_sector_price` | Sector index detail (breadth / 52-week range / intraday trend) | ka20001 |
+| `get_sector_stocks` | Member stocks of a sector with quotes | ka20002 |
 | `get_ranking` | Top gainers / losers / volume / trading value | ka10027/30/32 |
 | `get_market_movers` | New highs / new lows / upper & lower limit / surges / plunges | ka10016/17/19 |
 | `get_investor_trend` | Retail / foreign / institutional net-buy trend (period sum + daily) | ka10059, ka10061 |
-| `get_etf_info` | ETF tracking index / tax type / quote | ka40002, ka10001 |
+| `get_etf_info` | ETF tracking index / tax type / quote / NAV & disparity | ka40002, ka10001, ka40009 |
+| `get_etf_returns` | ETF period returns (1w/1m/6m/1y) vs a benchmark index | ka40001 |
 | `get_short_selling` | Per-stock daily short-selling trend (short volume / weight / avg price) | ka10014 |
 | `get_foreign_holding` | Per-stock foreign holding trend (holdings / holding weight / limit-usage rate) | ka10008 |
 

package/README.md

@@ -23,13 +23,16 @@ Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·
 |---|---|---|
 | `search_stock` | 종목명→코드 검색 (코스피/코스닥, ETF/ETN 포함) | ka10099 |
 | `get_stock_price` | 현재가/등락률/거래량/기본지표 | ka10001 |
-| `get_stock_chart` | 일/주/월/분봉 캔들 차트 (수정주가 반영) | ka10080~83 |
+| `get_stock_chart` | 일/주/월/년/분/틱봉 캔들 차트 (수정주가 반영) | ka10079~83, ka10094 |
 | `get_orderbook` | 10단계 매도/매수 호가·잔량 | ka10004 |
 | `get_market_index` | 코스피/코스닥 종합·업종 지수 | ka20003 |
+| `get_sector_price` | 업종 지수 현재가 상세 (등락 구성·52주 고저·시간대별 추이) | ka20001 |
+| `get_sector_stocks` | 업종 구성 종목 시세 (현재가·등락률·거래량·고저가) | ka20002 |
 | `get_ranking` | 상승률/하락률/거래량/거래대금 상위 | ka10027/30/32 |
 | `get_market_movers` | 신고가/신저가/상한가/하한가/급등/급락 특이 종목 | ka10016/17/19 |
 | `get_investor_trend` | 개인/외국인/기관 순매수 동향 (기간 합계 + 일별) | ka10059, ka10061 |
-| `get_etf_info` | ETF 추적지수·과세유형·시세 | ka40002, ka10001 |
+| `get_etf_info` | ETF 추적지수·과세유형·시세·NAV/괴리율 | ka40002, ka10001, ka40009 |
+| `get_etf_returns` | ETF 기간별(1주/1개월/6개월/1년) 수익률 vs 대상지수 | ka40001 |
 | `get_short_selling` | 종목별 일자별 공매도 추이 (공매도량·비중·평균가) | ka10014 |
 | `get_foreign_holding` | 종목별 외국인 보유 추이 (보유주식수·보유비중·한도소진률) | ka10008 |
 

package/dist/kiwoom/api.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { sleep } from "../utils/sleep.js";
 import { KiwoomApiError } from "./errors.js";
-import { accountEvaluationResponseSchema, allIndexResponseSchema, dailyChartItemSchema, depositResponseSchema, etfInfoResponseSchema, foreignHoldingResponseSchema, investorDailyItemSchema, investorTotalItemSchema, limitStockItemSchema, minuteChartItemSchema, newHighLowItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, priceJumpItemSchema, realizedPnlResponseSchema, shortSellingResponseSchema, stockInfoResponseSchema, stockListResponseSchema, themeGroupsResponseSchema, tradingJournalResponseSchema, themeStocksResponseSchema, transactionsResponseSchema, valueRankItemSchema, volumeRankItemSchema, watchlistGroupDetailResponseSchema, watchlistGroupsResponseSchema, } from "./types.js";
+import { accountEvaluationResponseSchema, allIndexResponseSchema, dailyChartItemSchema, depositResponseSchema, etfInfoResponseSchema, etfNavItemSchema, etfReturnItemSchema, foreignHoldingResponseSchema, investorDailyItemSchema, investorTotalItemSchema, limitStockItemSchema, minuteChartItemSchema, newHighLowItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, priceJumpItemSchema, realizedPnlResponseSchema, sectorPriceResponseSchema, sectorStocksResponseSchema, shortSellingResponseSchema, stockInfoResponseSchema, stockListResponseSchema, themeGroupsResponseSchema, tradingJournalResponseSchema, themeStocksResponseSchema, transactionsResponseSchema, valueRankItemSchema, volumeRankItemSchema, watchlistGroupDetailResponseSchema, watchlistGroupsResponseSchema, } from "./types.js";
 const STOCK_INFO_PATH = "/api/dostk/stkinfo";
 const ACCOUNT_PATH = "/api/dostk/acnt";
 const CHART_PATH = "/api/dostk/chart";
@@ -136,11 +136,13 @@ const CHART_TRS = {
     day: { apiId: "ka10081", arrayKey: "stk_dt_pole_chart_qry" },
     week: { apiId: "ka10082", arrayKey: "stk_stk_pole_chart_qry" },
     month: { apiId: "ka10083", arrayKey: "stk_mth_pole_chart_qry" },
+    year: { apiId: "ka10094", arrayKey: "stk_yr_pole_chart_qry" },
 };
 /**
- * ka10081/82/83 일·주·월봉 — newest first; first page (240~600 rows) only,
- * which is plenty for LLM consumption and avoids pagination rate-limit cost.
- * upd_stkpc_tp "1" = 수정주가 반영.
+ * ka10081/82/83/94 일·주·월·년봉 — same item shape, array key differs per TR
+ * (년봉 rows carry no pred_pre — schema defaults cover it). Newest first;
+ * first page (년봉 ~30, others 240~600 rows) only, which is plenty for LLM
+ * consumption and avoids pagination rate-limit cost. upd_stkpc_tp "1" = 수정주가 반영.
  */
 export async function fetchDailyChart(client, stockCode, period, baseDate) {
     const { apiId, arrayKey } = CHART_TRS[period];
@@ -160,6 +162,19 @@ export async function fetchMinuteChart(client, stockCode, ticScope) {
     });
     return parseArray(res.json, "stk_min_pole_chart_qry", minuteChartItemSchema);
 }
+/**
+ * ka10079 틱차트 — tic_scope = 캔들당 틱 수 ("1"|"3"|"5"|"10"|"30"). Row shape는
+ * ka10080 분봉과 동일(cntr_tm 포함; top-level last_tic_cnt는 미소비). Newest first,
+ * first page (900 rows) only.
+ */
+export async function fetchTickChart(client, stockCode, ticScope) {
+    const res = await client.call({
+        path: CHART_PATH,
+        apiId: "ka10079",
+        body: { stk_cd: stockCode, tic_scope: ticScope, upd_stkpc_tp: "1" },
+    });
+    return parseArray(res.json, "stk_tic_chart_qry", minuteChartItemSchema);
+}
 /** ka10004 주식호가 — 10-level orderbook; levels 2-10 live in the loose passthrough. */
 export async function fetchOrderbook(client, stockCode) {
     const res = await client.call({
@@ -178,6 +193,35 @@ export async function fetchAllIndices(client, indsCd) {
     });
     return allIndexResponseSchema.parse(res.json).all_inds_idex;
 }
+/**
+ * ka20001/ka20002의 mrkt_tp는 inds_cd 선행 자리에서 유도한다
+ * (0xx→"0" 코스피, 1xx→"1" 코스닥, 2xx→"2" 코스피200; mock-probed 2026-07-09).
+ * inds_cd 자체는 ka20003의 업종코드 공간을 그대로 쓴다.
+ */
+function sectorMarketType(indsCd) {
+    return indsCd.startsWith("1") ? "1" : indsCd.startsWith("2") ? "2" : "0";
+}
+/** ka20001 업종현재가 — 업종 지수 스냅샷 + 시간대별 추이. */
+export async function fetchSectorPrice(client, indsCd) {
+    const res = await client.call({
+        path: SECTOR_PATH,
+        apiId: "ka20001",
+        body: { mrkt_tp: sectorMarketType(indsCd), inds_cd: indsCd },
+    });
+    return sectorPriceResponseSchema.parse(res.json);
+}
+/**
+ * ka20002 업종별주가 — 업종 구성 종목의 시세. 100행/페이지(종목코드순)이며
+ * 첫 페이지만 가져온다; 남은 페이지가 있으면 truncated로 알린다.
+ */
+export async function fetchSectorStocks(client, indsCd) {
+    const res = await client.call({
+        path: SECTOR_PATH,
+        apiId: "ka20002",
+        body: { mrkt_tp: sectorMarketType(indsCd), inds_cd: indsCd, stex_tp: "1" },
+    });
+    return { items: sectorStocksResponseSchema.parse(res.json).inds_stkpc, truncated: res.hasNext };
+}
 /** amt_qty_tp: "1"=금액(백만원), "2"=수량(주) — 순매수(trde_tp "0") 기준. */
 const INVESTOR_UNIT_CODES = { amount: "1", quantity: "2" };
 /** ka10061 종목별투자자기관종합 — investor net-buy totals over a date range. */
@@ -277,6 +321,45 @@ export async function fetchEtfInfo(client, stockCode) {
     });
     return etfInfoResponseSchema.parse(res.json);
 }
+/** ka40001의 dt(기간) 코드 — 조회 순서대로 4행 테이블을 만든다. */
+export const ETF_RETURN_PERIODS = [
+    { dt: "0", label: "1주" },
+    { dt: "1", label: "1개월" },
+    { dt: "2", label: "6개월" },
+    { dt: "3", label: "1년" },
+];
+/**
+ * ka40001 ETF수익율 — 기간(dt)별 ETF 수익률 + 대상지수 수익률. mock-probed
+ * 2026-07-09: etfobjt_idex_cd는 필수(빈값 → 1511 오류)지만 ETF와 대조 검증되지
+ * 않는 "벤치마크 지수 선택자"다 — cntr_prft_rt가 그 지수의 기간 수익률로 채워진다.
+ * 4개 dt를 순차 호출(같은 TR — 레이트리밋 1.1s 간격)해 기간 순서대로 돌려준다.
+ */
+export async function fetchEtfReturns(client, stockCode, benchmarkIndexCode) {
+    const rows = [];
+    for (const [i, period] of ETF_RETURN_PERIODS.entries()) {
+        if (i > 0)
+            await sleep(PAGE_INTERVAL_MS);
+        const res = await client.call({
+            path: ETF_PATH,
+            apiId: "ka40001",
+            body: { stk_cd: stockCode, etfobjt_idex_cd: benchmarkIndexCode, dt: period.dt },
+        });
+        rows.push(parseArray(res.json, "etfprft_rt_lst", etfReturnItemSchema)[0] ?? null);
+    }
+    return rows;
+}
+/**
+ * ka40009 ETF NAV 추이 — 최신순 배열(etfnavarray)이지만 행에 시각 필드가 없다.
+ * mock에서는 NAV 관련 필드가 전부 빈 문자열 — 호출부는 빈값을 허용해야 한다.
+ */
+export async function fetchEtfNav(client, stockCode) {
+    const res = await client.call({
+        path: ETF_PATH,
+        apiId: "ka40009",
+        body: { stk_cd: stockCode },
+    });
+    return parseArray(res.json, "etfnavarray", etfNavItemSchema);
+}
 /**
  * ka01300 관심종목 그룹 리스트 조회 — HTS에 저장된 관심종목 그룹 목록 (읽기 전용).
  * 응답 배열 키는 nofi. 편집(추가/삭제) TR은 키움 REST에 존재하지 않는다.

package/dist/kiwoom/types.js

@@ -195,6 +195,57 @@ export const allIndexResponseSchema = z.looseObject({
     ...envelope,
     all_inds_idex: z.array(indexItemSchema).default([]),
 });
+// ── ka20001: 업종현재가 (subset) ──
+/** 시간대별 행 (`*_n` suffix). tm_n "999999"/"888888"은 장마감 집계 센티널 — 표시 시 필터. */
+export const sectorTimeRowSchema = z.looseObject({
+    tm_n: str(),
+    cur_prc_n: str(),
+    pred_pre_n: str(),
+    flu_rt_n: str(),
+    acc_trde_qty_n: str(), // 누적 거래량 (천주)
+});
+export const sectorPriceResponseSchema = z.looseObject({
+    ...envelope,
+    cur_prc: str(), // 지수 (소수점, 부호 접두)
+    pred_pre: str(),
+    flu_rt: str(),
+    trde_qty: str(), // 천주 (ka20003과 동일 단위)
+    trde_prica: str(), // 백만원
+    trde_frmatn_stk_num: str(), // 거래형성 종목수
+    trde_frmatn_rt: str(), // 거래형성 비율(%), 부호 접두
+    open_pric: str(),
+    high_pric: str(),
+    low_pric: str(),
+    upl: str(), // 상한 종목수
+    rising: str(),
+    stdns: str(), // 보합
+    fall: str(),
+    lst: str(), // 하한 종목수
+    "52wk_hgst_pric": str(),
+    "52wk_hgst_pric_dt": str(), // yyyyMMdd
+    "52wk_hgst_pric_pre_rt": str(), // 현재가의 52주 최고 대비 등락률
+    "52wk_lwst_pric": str(),
+    "52wk_lwst_pric_dt": str(),
+    "52wk_lwst_pric_pre_rt": str(),
+    inds_cur_prc_tm: z.array(sectorTimeRowSchema).default([]),
+});
+// ── ka20002: 업종별주가 (subset) ──
+export const sectorStockItemSchema = z.looseObject({
+    stk_cd: str(),
+    stk_nm: str(),
+    cur_prc: str(),
+    pred_pre_sig: str(),
+    pred_pre: str(),
+    flu_rt: str(),
+    now_trde_qty: str(),
+    open_pric: str(),
+    high_pric: str(),
+    low_pric: str(),
+});
+export const sectorStocksResponseSchema = z.looseObject({
+    ...envelope,
+    inds_stkpc: z.array(sectorStockItemSchema).default([]),
+});
 // ── ka10059/ka10061: 종목별 투자자·기관 (13-field investor breakdown) ──
 // amt_qty_tp "1"=금액(백만원), "2"=수량(주) — cross-checked live against volume.
 const investorFields = {
@@ -259,6 +310,26 @@ export const etfInfoResponseSchema = z.looseObject({
     etftxon_type: str(), // ETF 과세유형 ("비과세" 등)
     etntxon_type: str(),
 });
+// ── ka40001: ETF수익율 (array key etfprft_rt_lst; mock-probed 2026-07-09) ──
+// NOTE: cntr_prft_rt is the period return of the index selected by the
+// etfobjt_idex_cd REQUEST field (not validated against the ETF) — probed:
+// same code → same value regardless of stk_cd; bogus code → "0.00".
+export const etfReturnItemSchema = z.looseObject({
+    etfprft_rt: str(), // ETF 기간 수익률(%)
+    cntr_prft_rt: str(), // 대상지수(etfobjt_idex_cd) 기간 수익률(%)
+    for_netprps_qty: str(), // 외인 순매수량
+    orgn_netprps_qty: str(), // 기관 순매수량 (mock: blank)
+});
+// ── ka40009: ETF NAV 추이 (array key etfnavarray, newest first, no time field) ──
+// Rows carry NO timestamp; NAV/괴리율/추적오차 fields arrive blank on mock —
+// only stkcnt/base_pric are populated there. Callers must tolerate blanks.
+export const etfNavItemSchema = z.looseObject({
+    nav: str(),
+    navpred_pre: str(), // NAV 전일대비
+    navflu_rt: str(), // NAV 등락률(%)
+    trace_eor_rt: str(), // 추적오차율(%)
+    dispty_rt: str(), // 괴리율(%)
+});
 // ── ka01300/ka01301: 관심종목 그룹 (HTS 저장 그룹, live-verified 2026-07-06) ──
 // NOTE: array keys are nofi(그룹)/nofj(종목); item fields are terse (gcod/name,
 // cod2/bgb) and differ from the usual snake_case TRs. The response also carries

package/dist/server.js

@@ -3,6 +3,7 @@ import { isIsaEnabled } from "./config.js";
 import { registerAccountBalanceTool } from "./tools/account-balance.js";
 import { registerAccountHoldingsTool } from "./tools/account-holdings.js";
 import { registerEtfInfoTool } from "./tools/etf-info.js";
+import { registerEtfReturnsTool } from "./tools/etf-returns.js";
 import { registerForeignHoldingTool } from "./tools/foreign-holding.js";
 import { registerInvestorTrendTool } from "./tools/investor-trend.js";
 import { registerIsaTaxStatusTool } from "./tools/isa-tax-status.js";
@@ -12,6 +13,7 @@ import { registerOrderbookTool } from "./tools/orderbook.js";
 import { registerPendingOrdersTool } from "./tools/pending-orders.js";
 import { registerPingTool } from "./tools/ping.js";
 import { registerRankingTool } from "./tools/ranking.js";
+import { registerSectorPriceTool, registerSectorStocksTool } from "./tools/sector.js";
 import { registerShortSellingTool } from "./tools/short-selling.js";
 import { registerStockChartTool } from "./tools/stock-chart.js";
 import { registerStockPriceTool } from "./tools/stock-price.js";
@@ -21,7 +23,7 @@ import { registerTradingJournalTool } from "./tools/trading-journal.js";
 import { registerTransactionsTool } from "./tools/transactions.js";
 import { registerWatchlistGroupsTool, registerWatchlistTool } from "./tools/watchlist.js";
 export const SERVER_NAME = "kiwoom-mcp-server";
-export const SERVER_VERSION = "0.9.0";
+export const SERVER_VERSION = "0.12.0";
 export function createServer() {
     const server = new McpServer({
         name: SERVER_NAME,
@@ -34,10 +36,13 @@ export function createServer() {
     registerStockChartTool(server);
     registerOrderbookTool(server);
     registerMarketIndexTool(server);
+    registerSectorPriceTool(server);
+    registerSectorStocksTool(server);
     registerRankingTool(server);
     registerMarketMoversTool(server);
     registerInvestorTrendTool(server);
     registerEtfInfoTool(server);
+    registerEtfReturnsTool(server);
     registerShortSellingTool(server);
     registerForeignHoldingTool(server);
     // Watchlist (HTS 저장 관심종목 — read-only; ka01300/ka01301)

package/dist/tools/etf-info.js

@@ -1,9 +1,9 @@
 import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
-import { fetchEtfInfo, fetchStockInfo } from "../kiwoom/api.js";
-import { formatKRW, formatPercent, formatQuantity, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
+import { fetchEtfInfo, fetchEtfNav, fetchStockInfo } from "../kiwoom/api.js";
+import { formatKRW, formatPercent, formatQuantity, formatRatioPercent, formatSigned, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
-export function formatEtfInfo(etf, quote, stockCode, modeLabel) {
+export function formatEtfInfo(etf, quote, nav, stockCode, modeLabel) {
     if (!etf.stk_nm) {
         return `[${modeLabel}] ${stockCode}의 ETF 정보가 없습니다. ETF 종목코드인지 확인해 주세요.`;
     }
@@ -16,14 +16,21 @@ export function formatEtfInfo(etf, quote, stockCode, modeLabel) {
     if (quote) {
         lines.push(`- 현재가: ${formatKRW(parseKiwoomPrice(quote.cur_prc))} (${formatPercent(parseKiwoomNumber(quote.flu_rt))})`, `- 거래량: ${formatQuantity(parseKiwoomNumber(quote.trde_qty))}`);
     }
+    // ka40009 NAV — 필드가 빈값으로 오는 환경(mock 확인)이 있어 값이 있을 때만 표시.
+    const navValue = parseKiwoomPrice(nav?.nav);
+    if (nav && navValue !== null) {
+        lines.push(`- NAV: ${formatKRW(navValue)} (전일대비 ${formatSigned(parseKiwoomNumber(nav.navpred_pre))}, ` +
+            `${formatPercent(parseKiwoomNumber(nav.navflu_rt))})`, `- 괴리율: ${formatPercent(parseKiwoomNumber(nav.dispty_rt))} · ` +
+            `추적오차율: ${formatRatioPercent(parseKiwoomNumber(nav.trace_eor_rt))}`);
+    }
     lines.push("", "※ 과세유형은 키움 표기 기준입니다. 매매차익 과세 방식(국내주식형 비과세 vs 배당소득 과세)은 " +
-        "계좌 유형에 따라 달라질 수 있습니다.");
+        "계좌 유형에 따라 달라질 수 있습니다.", "※ 기간별(1주/1개월/6개월/1년) 수익률은 get_etf_returns로 조회할 수 있습니다.");
     return lines.join("\n");
 }
 export function registerEtfInfoTool(server) {
     server.registerTool("get_etf_info", {
         title: "ETF 정보 조회",
-        description: "ETF의 추적지수, 과세유형, 현재 시세를 조회합니다 (키움 ka40002+ka10001). " +
+        description: "ETF의 추적지수, 과세유형, 현재 시세, NAV·괴리율을 조회합니다 (키움 ka40002+ka10001+ka40009). " +
             "종목코드를 모르면 search_stock으로 먼저 찾으세요.",
         inputSchema: {
             stock_code: z
@@ -34,11 +41,12 @@ export function registerEtfInfoTool(server) {
     }, async ({ stock_code }) => runTool(async () => {
         const { client, config } = getKiwoomContext();
         const code = stock_code.toUpperCase();
-        // Different TRs — parallel is fine; the quote is best-effort garnish.
-        const [etf, quote] = await Promise.all([
+        // Different TRs — parallel is fine; quote and NAV are best-effort garnish.
+        const [etf, quote, navRows] = await Promise.all([
             fetchEtfInfo(client, code),
             fetchStockInfo(client, code).catch(() => null),
+            fetchEtfNav(client, code).catch(() => null),
         ]);
-        return textResult(formatEtfInfo(etf, quote, code, config.modeLabel));
+        return textResult(formatEtfInfo(etf, quote, navRows?.[0] ?? null, code, config.modeLabel));
     }));
 }

package/dist/tools/etf-returns.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { ETF_RETURN_PERIODS, fetchEtfInfo, fetchEtfReturns } from "../kiwoom/api.js";
+import { formatPercent, formatSigned, parseKiwoomNumber } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+import { sectorLabel } from "./sector.js";
+/** ka40001의 etfobjt_idex_cd는 필수 — 지정이 없으면 KOSPI200(201)을 기본 벤치마크로 쓴다. */
+const DEFAULT_BENCHMARK = "201";
+export function formatEtfReturns(rows, etfName, stockCode, benchmarkCode, modeLabel) {
+    const n = parseKiwoomNumber;
+    if (rows.every((r) => r === null || n(r.etfprft_rt) === null)) {
+        return (`[${modeLabel}] ${stockCode}의 ETF 수익률 데이터가 없습니다. ` +
+            `ETF 종목코드인지 확인해 주세요 (search_stock으로 검색 가능).`);
+    }
+    const title = etfName ? `${etfName} (${stockCode})` : stockCode;
+    const lines = [
+        `[${modeLabel}] ${title} ETF 기간 수익률`,
+        "",
+        "| 기간 | ETF 수익률 | 대상지수 수익률 | 외인 순매수량 | 기관 순매수량 |",
+        "|---|---:|---:|---:|---:|",
+    ];
+    for (const [i, period] of ETF_RETURN_PERIODS.entries()) {
+        const row = rows[i] ?? null;
+        lines.push(`| ${period.label} | ${formatPercent(n(row?.etfprft_rt))} | ${formatPercent(n(row?.cntr_prft_rt))} | ` +
+            `${formatSigned(n(row?.for_netprps_qty), 0)} | ${formatSigned(n(row?.orgn_netprps_qty), 0)} |`);
+    }
+    lines.push("", `※ 대상지수: ${benchmarkCode} (${sectorLabel(benchmarkCode)}) — benchmark_index_code로 변경할 수 ` +
+        `있습니다 (get_market_index의 '코드' 값).`);
+    return lines.join("\n");
+}
+export function registerEtfReturnsTool(server) {
+    server.registerTool("get_etf_returns", {
+        title: "ETF 기간 수익률 조회",
+        description: "ETF의 기간별(1주/1개월/6개월/1년) 수익률을 대상지수 수익률과 나란히 조회합니다 (키움 ka40001). " +
+            `대상지수는 benchmark_index_code로 지정하며 기본값은 ${DEFAULT_BENCHMARK}(KOSPI200)입니다 — ` +
+            "코드는 get_market_index의 '코드' 값을 사용하세요 (001 코스피 종합, 101 코스닥 종합 등). " +
+            "종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        inputSchema: {
+            stock_code: z
+                .string()
+                .regex(/^[0-9A-Z]{6}$/i, "6자리 종목코드여야 합니다")
+                .describe("6자리 ETF 종목코드 (예: 069500)"),
+            benchmark_index_code: z
+                .string()
+                .regex(/^\d{3}$/)
+                .optional()
+                .describe(`비교할 지수 코드 3자리 (기본값 ${DEFAULT_BENCHMARK} KOSPI200 — get_market_index의 '코드' 값)`),
+        },
+    }, async ({ stock_code, benchmark_index_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const code = stock_code.toUpperCase();
+        const benchmark = benchmark_index_code ?? DEFAULT_BENCHMARK;
+        // 4-period loop (~3.3s, same-TR rate limit) + name garnish in parallel.
+        const [rows, etf] = await Promise.all([
+            fetchEtfReturns(client, code, benchmark),
+            fetchEtfInfo(client, code).catch(() => null),
+        ]);
+        return textResult(formatEtfReturns(rows, etf?.stk_nm || null, code, benchmark, config.modeLabel));
+    }));
+}

package/dist/tools/market-index.js

@@ -11,21 +11,23 @@ export function formatIndices(items, market, modeLabel) {
     const lines = [
         `[${modeLabel}] ${MARKET_LABELS[market]} 업종 지수 (${items.length}개)`,
         "",
-        "| 지수 | 현재 | 전일대비 | 등락률 | 상승/보합/하락 |",
-        "|---|---:|---:|---:|---:|",
+        "| 지수 | 코드 | 현재 | 전일대비 | 등락률 | 상승/보합/하락 |",
+        "|---|---|---:|---:|---:|---:|",
     ];
     for (const item of items) {
-        lines.push(`| ${item.stk_nm} | ${formatNumber(parseKiwoomPrice(item.cur_prc))} | ` +
+        lines.push(`| ${item.stk_nm} | ${item.stk_cd || "-"} | ${formatNumber(parseKiwoomPrice(item.cur_prc))} | ` +
             `${formatSigned(parseKiwoomNumber(item.pred_pre))} | ${formatPercent(parseKiwoomNumber(item.flu_rt))} | ` +
             `${parseKiwoomNumber(item.rising) ?? "-"}/${parseKiwoomNumber(item.stdns) ?? "-"}/${parseKiwoomNumber(item.fall) ?? "-"} |`);
     }
+    lines.push("", "※ 업종 상세·구성종목은 get_sector_price / get_sector_stocks에 '코드' 값을 넣어 조회하세요.");
     return lines.join("\n");
 }
 export function registerMarketIndexTool(server) {
     server.registerTool("get_market_index", {
         title: "시장 지수 조회",
         description: "코스피/코스닥 종합지수와 업종별 지수를 조회합니다 (키움 ka20003). " +
-            "첫 행이 시장 종합지수, 이후는 업종 지수입니다.",
+            "첫 행이 시장 종합지수, 이후는 업종 지수입니다. 각 행의 '코드'는 " +
+            "get_sector_price / get_sector_stocks의 sector_code로 사용할 수 있습니다.",
         inputSchema: {
             market: z
                 .enum(["kospi", "kosdaq"])

package/dist/tools/sector.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchSectorPrice, fetchSectorStocks } from "../kiwoom/api.js";
+import { formatDateDashed } from "../utils/date.js";
+import { formatNumber, formatPercent, formatRatioPercent, formatSigned, parseKiwoomNumber, parseKiwoomPrice, } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_STOCK_LIMIT = 30;
+const MAX_STOCK_LIMIT = 100;
+const TIME_ROWS_SHOWN = 10;
+/** 잘 알려진 업종 코드 라벨 — 전체 코드 목록은 get_market_index로 조회. */
+const SECTOR_LABELS = {
+    "001": "코스피 종합",
+    "002": "코스피 대형주",
+    "101": "코스닥 종합",
+    "201": "KOSPI200",
+};
+export const sectorLabel = (code) => SECTOR_LABELS[code] ?? `업종 ${code}`;
+/** "153220" → "15:32:20"; 시각이 아닌 값(장마감 센티널 999999/888888 등)은 null. */
+function formatSectorTime(tm) {
+    if (!/^\d{6}$/.test(tm) || Number(tm.slice(0, 2)) > 23)
+        return null;
+    return `${tm.slice(0, 2)}:${tm.slice(2, 4)}:${tm.slice(4, 6)}`;
+}
+const dashedOr = (yyyymmdd) => /^\d{8}$/.test(yyyymmdd) ? formatDateDashed(yyyymmdd) : "-";
+export function formatSectorPrice(res, sectorCode, modeLabel) {
+    const n = parseKiwoomNumber;
+    const p = parseKiwoomPrice;
+    const index = p(res.cur_prc);
+    if (index === null) {
+        return (`[${modeLabel}] 업종 ${sectorCode}의 시세 데이터가 없습니다. ` +
+            `업종 코드를 확인하세요 (get_market_index의 '코드' 값).`);
+    }
+    const lines = [
+        `[${modeLabel}] 업종 현재가 — ${sectorLabel(sectorCode)} (${sectorCode})`,
+        "",
+        `지수 ${formatNumber(index)} (전일대비 ${formatSigned(n(res.pred_pre))}, ${formatPercent(n(res.flu_rt))})`,
+        `시가 ${formatNumber(p(res.open_pric))} · 고가 ${formatNumber(p(res.high_pric))} · 저가 ${formatNumber(p(res.low_pric))}`,
+        `거래량 ${formatNumber(n(res.trde_qty), 0)}천주 · 거래대금 ${formatNumber(n(res.trde_prica), 0)}백만원`,
+        `등락 구성: 상한 ${n(res.upl) ?? "-"} · 상승 ${n(res.rising) ?? "-"} · 보합 ${n(res.stdns) ?? "-"} · ` +
+            `하락 ${n(res.fall) ?? "-"} · 하한 ${n(res.lst) ?? "-"} ` +
+            `(거래형성 ${formatNumber(n(res.trde_frmatn_stk_num), 0)}종목, ${formatRatioPercent(p(res.trde_frmatn_rt))})`,
+        `52주 최고 ${formatNumber(p(res["52wk_hgst_pric"]))} (${dashedOr(res["52wk_hgst_pric_dt"])}, ` +
+            `현재 대비 ${formatPercent(n(res["52wk_hgst_pric_pre_rt"]))}) · ` +
+            `최저 ${formatNumber(p(res["52wk_lwst_pric"]))} (${dashedOr(res["52wk_lwst_pric_dt"])}, ` +
+            `현재 대비 ${formatPercent(n(res["52wk_lwst_pric_pre_rt"]))})`,
+    ];
+    const timeRows = [];
+    for (const row of res.inds_cur_prc_tm) {
+        const time = formatSectorTime(row.tm_n);
+        if (time)
+            timeRows.push({ time, row });
+        if (timeRows.length >= TIME_ROWS_SHOWN)
+            break;
+    }
+    if (timeRows.length > 0) {
+        lines.push("", `시간대별 추이 (최근 ${timeRows.length}건)`, "", "| 시각 | 지수 | 전일대비 | 등락률 | 누적거래량(천주) |", "|---|---:|---:|---:|---:|");
+        for (const { time, row } of timeRows) {
+            lines.push(`| ${time} | ${formatNumber(p(row.cur_prc_n))} | ${formatSigned(n(row.pred_pre_n))} | ` +
+                `${formatPercent(n(row.flu_rt_n))} | ${formatNumber(n(row.acc_trde_qty_n), 0)} |`);
+        }
+    }
+    lines.push("", "※ 구성 종목별 시세는 get_sector_stocks에 같은 업종 코드를 넣어 조회하세요.");
+    return lines.join("\n");
+}
+export function formatSectorStocks(items, truncated, sectorCode, limit, modeLabel) {
+    if (items.length === 0) {
+        return (`[${modeLabel}] ${sectorLabel(sectorCode)} (${sectorCode})의 구성 종목이 없습니다. ` +
+            `업종 코드를 확인하세요 (get_market_index의 '코드' 값).`);
+    }
+    const n = parseKiwoomNumber;
+    const p = parseKiwoomPrice;
+    const shown = items.slice(0, limit);
+    const lines = [
+        `[${modeLabel}] 업종별 주가 — ${sectorLabel(sectorCode)} (${sectorCode}), ${shown.length}종목 (종목코드순)`,
+        "",
+        "| 종목명 | 코드 | 현재가 | 전일대비 | 등락률 | 거래량 | 고가 | 저가 |",
+        "|---|---|---:|---:|---:|---:|---:|---:|",
+    ];
+    for (const item of shown) {
+        lines.push(`| ${item.stk_nm || "-"} | ${item.stk_cd || "-"} | ${formatNumber(p(item.cur_prc), 0)} | ` +
+            `${formatSigned(n(item.pred_pre), 0)} | ${formatPercent(n(item.flu_rt))} | ` +
+            `${formatNumber(n(item.now_trde_qty), 0)} | ${formatNumber(p(item.high_pric), 0)} | ` +
+            `${formatNumber(p(item.low_pric), 0)} |`);
+    }
+    const notes = [];
+    if (items.length > shown.length) {
+        notes.push(`※ 첫 ${shown.length}종목만 표시했습니다 (limit으로 최대 ${MAX_STOCK_LIMIT}개까지 조정 가능).`);
+    }
+    if (truncated) {
+        notes.push("※ 구성 종목이 더 있습니다 — 이 조회는 첫 페이지(종목코드순 100종목)만 가져옵니다.");
+    }
+    if (notes.length > 0)
+        lines.push("", ...notes);
+    return lines.join("\n");
+}
+const sectorCodeSchema = z
+    .string()
+    .regex(/^\d{3}$/)
+    .describe("업종 코드 3자리 (예: 001 코스피 종합, 101 코스닥 종합 — get_market_index의 '코드' 값)");
+export function registerSectorPriceTool(server) {
+    server.registerTool("get_sector_price", {
+        title: "업종 현재가 조회",
+        description: "업종(섹터) 지수의 현재가 상세를 조회합니다 (키움 ka20001) — 지수·시/고/저가·거래량·" +
+            "상승/하락 종목수·52주 고저·시간대별 추이. sector_code는 get_market_index가 보여주는 " +
+            "업종 코드입니다 (001 코스피 종합, 002 코스피 대형주, 101 코스닥 종합, 201 KOSPI200 등).",
+        inputSchema: {
+            sector_code: sectorCodeSchema,
+        },
+    }, async ({ sector_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const res = await fetchSectorPrice(client, sector_code);
+        return textResult(formatSectorPrice(res, sector_code, config.modeLabel));
+    }));
+}
+export function registerSectorStocksTool(server) {
+    server.registerTool("get_sector_stocks", {
+        title: "업종별 종목 시세 조회",
+        description: "특정 업종에 속한 종목들의 시세를 조회합니다 (키움 ka20002). 종목코드순 정렬이며 " +
+            "첫 페이지(최대 100종목)만 가져옵니다. sector_code는 get_market_index의 업종 코드입니다.",
+        inputSchema: {
+            sector_code: sectorCodeSchema,
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_STOCK_LIMIT)
+                .optional()
+                .describe(`표시할 종목 수 (기본값 ${DEFAULT_STOCK_LIMIT}, 최대 ${MAX_STOCK_LIMIT})`),
+        },
+    }, async ({ sector_code, limit }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const { items, truncated } = await fetchSectorStocks(client, sector_code);
+        return textResult(formatSectorStocks(items, truncated, sector_code, limit ?? DEFAULT_STOCK_LIMIT, config.modeLabel));
+    }));
+}

package/dist/tools/stock-chart.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { getKiwoomContext } from "../context.js";
-import { fetchDailyChart, fetchMinuteChart } from "../kiwoom/api.js";
+import { fetchDailyChart, fetchMinuteChart, fetchTickChart } from "../kiwoom/api.js";
 import { formatDateDashed, todayInKst } from "../utils/date.js";
 import { formatNumber, parseKiwoomNumber, parseKiwoomPrice } from "../utils/num.js";
 import { runTool, textResult } from "./helpers.js";
@@ -10,7 +10,7 @@ const PERIOD_LABELS = {
     day: "일봉",
     week: "주봉",
     month: "월봉",
-    minute: "분봉",
+    year: "년봉",
 };
 /** "20260703153000" → "2026-07-03 15:30" */
 function formatMinuteTime(cntrTm) {
@@ -37,13 +37,14 @@ export function formatDailyChart(items, stockCode, period, count, modeLabel) {
     ];
     return lines.join("\n");
 }
-export function formatMinuteChart(items, stockCode, ticScope, count, modeLabel) {
+/** 분봉과 틱봉이 같은 행 구조(cntr_tm)를 공유 — scopeLabel은 "5분"/"30틱" 형태. */
+export function formatMinuteChart(items, stockCode, scopeLabel, count, modeLabel) {
     if (items.length === 0) {
-        return `[${modeLabel}] ${stockCode} 분봉 데이터가 없습니다. 종목코드를 확인해 주세요.`;
+        return `[${modeLabel}] ${stockCode} ${scopeLabel}봉 데이터가 없습니다. 종목코드를 확인해 주세요.`;
     }
     const shown = items.slice(0, count).reverse();
     const lines = [
-        `[${modeLabel}] ${stockCode} ${ticScope}분봉 차트 (최근 ${shown.length}개, 수정주가 반영)`,
+        `[${modeLabel}] ${stockCode} ${scopeLabel}봉 차트 (최근 ${shown.length}개, 수정주가 반영)`,
         "",
         "| 시각 | 시가 | 고가 | 저가 | 종가 | 거래량 |",
         "|---|---:|---:|---:|---:|---:|",
@@ -53,17 +54,18 @@ export function formatMinuteChart(items, stockCode, ticScope, count, modeLabel)
 }
 export function registerStockChartTool(server) {
     server.registerTool("get_stock_chart", {
-        title: "주식 차트 조회 (일/주/월/분봉)",
-        description: "종목의 캔들 차트 데이터를 조회합니다 (키움 ka10080~ka10083, 수정주가 반영). " +
-            "period: day(일봉, 기본)/week(주봉)/month(월봉)/minute(분봉). 분봉은 minute_scope로 " +
-            "분 단위를 지정합니다. 종목코드를 모르면 search_stock으로 먼저 찾으세요.",
+        title: "주식 차트 조회 (일/주/월/년/분/틱봉)",
+        description: "종목의 캔들 차트 데이터를 조회합니다 (키움 ka10079~ka10083/ka10094, 수정주가 반영). " +
+            "period: day(일봉, 기본)/week(주봉)/month(월봉)/year(년봉)/minute(분봉)/tick(틱봉). " +
+            "분봉은 minute_scope로 분 단위를, 틱봉은 tick_scope로 캔들당 틱 수를 지정합니다. " +
+            "종목코드를 모르면 search_stock으로 먼저 찾으세요.",
         inputSchema: {
             stock_code: z
                 .string()
                 .regex(/^[0-9A-Z]{6}$/i, "6자리 종목코드여야 합니다")
                 .describe("6자리 종목코드 (예: 005930)"),
             period: z
-                .enum(["day", "week", "month", "minute"])
+                .enum(["day", "week", "month", "year", "minute", "tick"])
                 .optional()
                 .describe("봉 주기 (기본값: day)"),
             count: z
@@ -77,15 +79,22 @@ export function registerStockChartTool(server) {
                 .enum(["1", "3", "5", "10", "15", "30", "45", "60"])
                 .optional()
                 .describe("period=minute일 때 분 단위 (기본값: 5)"),
+            tick_scope: z
+                .enum(["1", "3", "5", "10", "30"])
+                .optional()
+                .describe("period=tick일 때 캔들당 틱 수 (기본값: 30)"),
         },
-    }, async ({ stock_code, period, count, minute_scope }) => runTool(async () => {
+    }, async ({ stock_code, period, count, minute_scope, tick_scope }) => runTool(async () => {
         const { client, config } = getKiwoomContext();
         const code = stock_code.toUpperCase();
         const n = count ?? DEFAULT_COUNT;
-        if (period === "minute") {
-            const scope = minute_scope ?? "5";
-            const items = await fetchMinuteChart(client, code, scope);
-            return textResult(formatMinuteChart(items, code, scope, n, config.modeLabel));
+        if (period === "minute" || period === "tick") {
+            const isTick = period === "tick";
+            const scope = isTick ? (tick_scope ?? "30") : (minute_scope ?? "5");
+            const items = isTick
+                ? await fetchTickChart(client, code, scope)
+                : await fetchMinuteChart(client, code, scope);
+            return textResult(formatMinuteChart(items, code, `${scope}${isTick ? "틱" : "분"}`, n, config.modeLabel));
         }
         const p = period ?? "day";
         const items = await fetchDailyChart(client, code, p, todayInKst());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiwoom-mcp-server",
-  "version": "0.9.0",
+  "version": "0.12.0",
   "description": "Read-only MCP server exposing the Kiwoom Securities REST API (market data, account inquiry, ISA tax-allowance calculator) to Claude Desktop / Claude Code.",
   "private": false,
   "type": "module",