kiwoom-mcp-server 0.8.0

package/dist/tools/transactions.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchTransactions } from "../kiwoom/api.js";
+import { normalizeStockCode } from "../kiwoom/types.js";
+import { formatDateDashed, kstDaysAgo, todayInKst } from "../utils/date.js";
+import { formatKRW, parseKiwoomNumber } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const DEFAULT_LOOKBACK_DAYS = 30;
+export function formatTransactions(rows, query, modeLabel, truncated = false) {
+    const filtered = query.stockCode
+        ? rows.filter((r) => normalizeStockCode(r.stk_cd) === query.stockCode)
+        : rows;
+    const period = `${formatDateDashed(query.fromDate)} ~ ${formatDateDashed(query.toDate)}`;
+    const scope = query.stockCode ? `, 종목 ${query.stockCode}` : "";
+    if (filtered.length === 0) {
+        return `[${modeLabel}] 거래내역이 없습니다 (${period}${scope}).`;
+    }
+    const n = parseKiwoomNumber;
+    const lines = [
+        `[${modeLabel}] 계좌 거래내역 (${period}${scope}, ${filtered.length}건)`,
+        "",
+        "| 체결일 | 구분 | 종목 | 수량 | 단가 | 정산금액 | 수수료 |",
+        "|---|---|---|---:|---:|---:|---:|",
+    ];
+    for (const row of filtered) {
+        const kind = row.io_tp_nm || row.trde_kind_nm || row.rmrk_nm || "-";
+        const stock = row.stk_nm ? `${row.stk_nm} (${normalizeStockCode(row.stk_cd)})` : "-";
+        const cells = [
+            formatDateDashed(row.cntr_dt || row.trde_dt),
+            kind,
+            stock,
+            n(row.trde_qty_jwa_cnt)?.toLocaleString("ko-KR") ?? "-",
+            formatKRW(n(row.trde_unit)),
+            formatKRW(n(row.exct_amt)),
+            formatKRW(n(row.cmsn)),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    if (truncated) {
+        lines.push("", "⚠️ 거래가 많아 조회 상한에 도달했습니다 — 오래된 일부 거래가 누락되었을 수 있습니다. " +
+            "조회 기간(from_date~to_date)을 좁혀 다시 조회하세요.");
+    }
+    lines.push("", "※ 조회 기간과 결제는 체결 2영업일 후 기준이라, 최근 1~2영업일의 매매는 아직 결제 전이라 " +
+        "조회에 빠질 수 있습니다. 정산금액은 수수료·세금 반영 금액입니다.");
+    return lines.join("\n");
+}
+export function registerTransactionsTool(server) {
+    server.registerTool("get_transactions", {
+        title: "계좌 거래내역 조회",
+        description: "계좌의 거래내역(매수/매도 등)을 기간별로 조회합니다 (키움 kt00015). 기본 조회 기간은 " +
+            "최근 30일이며 from_date/to_date로 변경, stock_code로 특정 종목만 필터링할 수 있습니다. " +
+            "일자는 결제일(D+2) 기준입니다.",
+        inputSchema: {
+            from_date: z
+                .string()
+                .regex(/^\d{4}-?\d{2}-?\d{2}$/, "yyyy-MM-dd 또는 yyyyMMdd 형식이어야 합니다")
+                .optional()
+                .describe("조회 시작일 (기본값: 30일 전)"),
+            to_date: z
+                .string()
+                .regex(/^\d{4}-?\d{2}-?\d{2}$/, "yyyy-MM-dd 또는 yyyyMMdd 형식이어야 합니다")
+                .optional()
+                .describe("조회 종료일 (기본값: 오늘)"),
+            stock_code: z
+                .string()
+                .regex(/^\d{6}$/, "6자리 종목코드여야 합니다")
+                .optional()
+                .describe("특정 종목만 조회할 때의 6자리 종목코드"),
+        },
+    }, async ({ from_date, to_date, stock_code }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const query = {
+            fromDate: (from_date ?? kstDaysAgo(DEFAULT_LOOKBACK_DAYS)).replaceAll("-", ""),
+            toDate: (to_date ?? todayInKst()).replaceAll("-", ""),
+            stockCode: stock_code,
+        };
+        const { rows, truncated } = await fetchTransactions(client, query.fromDate, query.toDate);
+        return textResult(formatTransactions(rows, query, config.modeLabel, truncated));
+    }));
+}

package/dist/tools/watchlist.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import { getKiwoomContext } from "../context.js";
+import { fetchWatchlistGroupDetail, fetchWatchlistGroups } from "../kiwoom/api.js";
+import { KiwoomApiError } from "../kiwoom/errors.js";
+import { loadMasterList } from "../kiwoom/master-list.js";
+import { normalizeStockCode, } from "../kiwoom/types.js";
+import { formatKRW, parseKiwoomPrice } from "../utils/num.js";
+import { runTool, textResult } from "./helpers.js";
+const normalizeName = (s) => s.replaceAll(/\s+/g, "").toLowerCase();
+export function formatWatchlistGroups(groups, modeLabel) {
+    if (groups.length === 0) {
+        return (`[${modeLabel}] 등록된 관심종목 그룹이 없습니다. ` +
+            `영웅문(HTS)에서 관심종목 그룹을 먼저 만들어 주세요.`);
+    }
+    const [first] = groups;
+    const lines = [
+        `[${modeLabel}] 관심종목 그룹 (${groups.length}개)`,
+        "",
+        "| 그룹코드 | 그룹명 |",
+        "|---|---|",
+    ];
+    for (const g of groups) {
+        lines.push(`| ${g.gcod || "-"} | ${g.name || "-"} |`);
+    }
+    lines.push("", `특정 그룹의 종목을 보려면 get_watchlist에 그룹코드나 그룹명을 넘기세요 ` +
+        `(예: group="${first?.gcod ?? ""}" 또는 "${first?.name ?? ""}").`);
+    return lines.join("\n");
+}
+/** Matches by exact group code first, then by (whitespace-insensitive) name. */
+export function findWatchlistGroup(groups, query) {
+    const trimmed = query.trim();
+    if (trimmed === "")
+        return undefined;
+    const q = normalizeName(trimmed);
+    return (groups.find((g) => g.gcod === trimmed) ?? groups.find((g) => normalizeName(g.name) === q));
+}
+export function formatWatchlist(group, stocks, nameIndex, modeLabel) {
+    const title = `[${modeLabel}] 관심종목: ${group.name || "-"} (${group.gcod}) — ${stocks.length}종목`;
+    if (stocks.length === 0) {
+        return `${title}\n\n(이 그룹에 등록된 종목이 없습니다.)`;
+    }
+    const lines = [title, "", "| 코드 | 종목명 | 시장 | 전일종가 |", "|---|---|---|---:|"];
+    let missing = 0;
+    for (const s of stocks) {
+        const code = normalizeStockCode(s.cod2);
+        const info = nameIndex.get(code);
+        if (!info)
+            missing += 1;
+        const bookmark = s.bgb && s.bgb !== "0" ? "⭐ " : "";
+        const name = `${bookmark}${info?.name || "-"}`;
+        const market = info?.marketName || "-";
+        const price = info ? formatKRW(parseKiwoomPrice(info.lastPrice)) : "-";
+        lines.push(`| ${code} | ${name} | ${market} | ${price} |`);
+    }
+    if (nameIndex.size === 0) {
+        lines.push("", "※ 종목 마스터를 불러오지 못해 코드만 표시했습니다.");
+    }
+    else if (missing > 0) {
+        lines.push("", `※ ${missing}개 종목은 상장 마스터에 없어 상세정보를 표시하지 못했습니다.`);
+    }
+    return lines.join("\n");
+}
+/** Best-effort code→종목 index for name/전일종가 enrichment (no extra per-stock calls). */
+async function buildNameIndex(client, stocks) {
+    if (stocks.length === 0)
+        return new Map();
+    try {
+        const items = await loadMasterList(client);
+        return new Map(items.map((i) => [i.code, i]));
+    }
+    catch {
+        // Enrichment is optional — fall back to code-only rather than failing the tool.
+        return new Map();
+    }
+}
+export function registerWatchlistGroupsTool(server) {
+    server.registerTool("get_watchlist_groups", {
+        title: "관심종목 그룹 목록",
+        description: "영웅문(HTS)에 저장한 관심종목 그룹 목록(그룹코드+그룹명)을 조회합니다 (키움 ka01300, 읽기 전용). " +
+            "특정 그룹의 종목은 get_watchlist로 조회하세요. " +
+            "그룹 편집(추가/삭제)은 키움 REST API가 지원하지 않아 조회만 가능합니다.",
+        inputSchema: {},
+    }, async () => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const groups = await fetchWatchlistGroups(client);
+        return textResult(formatWatchlistGroups(groups, config.modeLabel));
+    }));
+}
+export function registerWatchlistTool(server) {
+    server.registerTool("get_watchlist", {
+        title: "관심종목 그룹 상세",
+        description: "관심종목 그룹에 담긴 종목 목록을 조회합니다 (키움 ka01301, 읽기 전용). " +
+            "그룹코드(예: '000') 또는 그룹명(예: 'etf')을 넘기세요. 그룹을 모르면 get_watchlist_groups로 먼저 확인하세요. " +
+            "종목명·전일종가·시장은 종목 마스터에서 보강해 함께 표시합니다.",
+        inputSchema: {
+            group: z
+                .string()
+                .min(1)
+                .describe("관심종목 그룹코드 또는 그룹명 (get_watchlist_groups로 확인)"),
+        },
+    }, async ({ group }) => runTool(async () => {
+        const { client, config } = getKiwoomContext();
+        const groups = await fetchWatchlistGroups(client);
+        const matched = findWatchlistGroup(groups, group);
+        if (!matched) {
+            const available = groups.length
+                ? groups.map((g) => `${g.gcod}(${g.name})`).join(", ")
+                : "(없음)";
+            throw new KiwoomApiError(`관심종목 그룹 "${group}"을(를) 찾을 수 없습니다. 사용 가능한 그룹: ${available}`, { apiId: "ka01301" });
+        }
+        const stocks = await fetchWatchlistGroupDetail(client, matched.gcod);
+        const nameIndex = await buildNameIndex(client, stocks);
+        return textResult(formatWatchlist(matched, stocks, nameIndex, config.modeLabel));
+    }));
+}

package/dist/utils/date.js

@@ -0,0 +1,15 @@
+/** Date helpers pinned to KST — the timezone of every Kiwoom API date field. */
+/** Today's date in KST as yyyyMMdd (sv-SE locale gives ISO ordering). */
+export function todayInKst() {
+    return new Date().toLocaleDateString("sv-SE", { timeZone: "Asia/Seoul" }).replaceAll("-", "");
+}
+/** KST date `days` days before today, yyyyMMdd. */
+export function kstDaysAgo(days) {
+    return new Date(Date.now() - days * 86_400_000)
+        .toLocaleDateString("sv-SE", { timeZone: "Asia/Seoul" })
+        .replaceAll("-", "");
+}
+/** yyyyMMdd → yyyy-MM-dd for display. */
+export function formatDateDashed(yyyymmdd) {
+    return `${yyyymmdd.slice(0, 4)}-${yyyymmdd.slice(4, 6)}-${yyyymmdd.slice(6, 8)}`;
+}

package/dist/utils/num.js

@@ -0,0 +1,67 @@
+/**
+ * Kiwoom REST API returns every numeric value as a string, often zero-padded
+ * and/or sign-prefixed (e.g. "000000061300", "+61300", "-00013000").
+ * Some TRs double the sign ("--23722054", live-observed on ka10061) — the
+ * leading sign run collapses to its first character. A few fields arrive
+ * comma-grouped ("20,190", kt00015 trde_unit). An empty string means
+ * "no value".
+ */
+export function parseKiwoomNumber(raw) {
+    if (raw == null)
+        return null;
+    const trimmed = raw.trim().replaceAll(",", "").replace(/^([+-])[+-]+/, "$1");
+    if (trimmed === "" || trimmed === "+" || trimmed === "-")
+        return null;
+    const value = Number(trimmed);
+    return Number.isFinite(value) ? value : null;
+}
+/**
+ * For price fields (cur_prc, open_pric, ...) Kiwoom encodes the direction
+ * versus yesterday as a +/- sign on the price itself. The actual price is the
+ * absolute value; direction should be read from pre_sig / pred_pre instead.
+ */
+export function parseKiwoomPrice(raw) {
+    const value = parseKiwoomNumber(raw);
+    return value === null ? null : Math.abs(value);
+}
+export function formatKRW(value) {
+    if (value === null)
+        return "-";
+    return `${value.toLocaleString("ko-KR", { maximumFractionDigits: 2 })}원`;
+}
+export function formatSignedKRW(value) {
+    if (value === null)
+        return "-";
+    const sign = value > 0 ? "+" : "";
+    return `${sign}${value.toLocaleString("ko-KR", { maximumFractionDigits: 2 })}원`;
+}
+export function formatQuantity(value) {
+    if (value === null)
+        return "-";
+    return `${value.toLocaleString("ko-KR")}주`;
+}
+export function formatPercent(value) {
+    if (value === null)
+        return "-";
+    const sign = value > 0 ? "+" : "";
+    return `${sign}${value.toFixed(2)}%`;
+}
+/** Non-directional ratio as a percent (no forced + sign): 46.58 → "46.58%". */
+export function formatRatioPercent(value) {
+    if (value === null)
+        return "-";
+    return `${value.toLocaleString("ko-KR", { maximumFractionDigits: 2 })}%`;
+}
+/** Plain locale-formatted number without a unit (indices, ratios, counts). */
+export function formatNumber(value, maxFractionDigits = 2) {
+    if (value === null)
+        return "-";
+    return value.toLocaleString("ko-KR", { maximumFractionDigits: maxFractionDigits });
+}
+/** Signed locale-formatted number without a unit (investor flows etc.). */
+export function formatSigned(value, maxFractionDigits = 2) {
+    if (value === null)
+        return "-";
+    const sign = value > 0 ? "+" : "";
+    return `${sign}${value.toLocaleString("ko-KR", { maximumFractionDigits: maxFractionDigits })}`;
+}

package/dist/utils/redact.js

@@ -0,0 +1,14 @@
+/**
+ * Removes secret values (app key/secret, tokens) from text that may be logged
+ * or returned to the MCP client, e.g. raw API response snippets in errors.
+ */
+export function redactSecrets(text, secrets) {
+    let out = text;
+    for (const secret of secrets) {
+        // Very short strings would over-redact; real keys/tokens are much longer.
+        if (secret && secret.length >= 8) {
+            out = out.replaceAll(secret, "***REDACTED***");
+        }
+    }
+    return out;
+}

package/dist/utils/sleep.js

@@ -0,0 +1,3 @@
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "kiwoom-mcp-server",
+  "version": "0.8.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",
+  "license": "MIT",
+  "author": "ChunSam",
+  "homepage": "https://github.com/ChunSam/kiwoom-mcp-server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChunSam/kiwoom-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ChunSam/kiwoom-mcp-server/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "kiwoom",
+    "kiwoom-securities",
+    "stock",
+    "korea-stock",
+    "isa",
+    "read-only"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "bin": {
+    "kiwoom-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.0.0"
+  }
+}