kiwoom-mcp-server

kiwoom-mcp-server

한국어 · English

키움증권 REST API를 조회 전용(read-only) 으로 노출하는 MCP 서버입니다. Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·호가·지수·순위·수급과 내 계좌의 잔고·보유 종목·거래내역을 조회할 수 있고, ISA 계좌라면 비과세 한도 대비 손익통산 현황까지 계산해 줍니다.

⚠️ 보안 경고

• 기본 실행은 로컬 stdio입니다. 원격에서 써야 한다면 반드시 인증이 내장된 HTTP 모드(원격 연결 참조)로만 노출하고, 인증 없는 상태(--no-auth)로는 절대 외부 네트워크에 열지 마세요.
• .env의 AppKey/AppSecret은 실계좌 조회 권한입니다. 절대 커밋하지 마세요 (.gitignore에 이미 등록되어 있습니다).
• 주문(매수/매도/정정/취소) 기능은 설계상 제외되어 있습니다. 이 서버가 계좌를 변경하는 일은 없습니다.

제공 Tool

시장 데이터 (계좌와 무관, 앱키만 있으면 사용 가능):

Tool	설명	키움 TR
search_stock	종목명→코드 검색 (코스피/코스닥, ETF/ETN 포함) + 투자유의 표시	ka10099
get_stock_price	현재가/등락률/거래량/기본지표 + 업종·상장일·투자유의	ka10001, ka10099
get_stock_quotes	여러 종목(최대 30개) 일괄 시세 — 현재가·등락률·거래량·거래대금·시가총액	ka10095, ka10099
get_stock_chart	일/주/월/년/분/틱봉 캔들 차트 (수정주가 반영)	ka10079~83, ka10094
get_daily_trading	일별 거래·수급 — 종가·거래대금 + 개인/기관/외국인 순매수·프로그램·신용비율, 또는 장전/장중/장후 거래 분포	ka10086, ka10015
get_orderbook	10단계 매도/매수 호가·잔량 (통합 기준)	ka10007
get_orderbook_rank	시장 전체 호가잔량 상위 / 잔량 급증 / 잔량비율 급증 (정규장 중)	ka10020~22
get_market_index	코스피/코스닥 종합·업종 지수	ka20003
get_sector_price	업종 지수 현재가 상세 (등락 구성·52주 고저·시간대별 추이)	ka20001
get_sector_stocks	업종 구성 종목 시세 (현재가·등락률·거래량·고저가)	ka20002
get_sector_chart	업종 지수 일/주/월/년/분/틱봉 캔들 차트	ka20004~08, ka20019
get_sector_flow	업종별 투자자 순매수 — 시장 전체 업종의 개인/외국인/기관계 + 증권·투신·연기금·사모	ka10051
get_ranking	상승률/하락률/거래량/거래대금 상위 + 시가대비 등락률(체결강도 포함) + 신용비율 상위	ka10027/30/32, ka10028, ka10033
get_equal_net_trade	기관·외국인이 동시에 같은 방향으로 순매매한 종목 + 주체별 추정 평균단가	ka10062
get_valuation_rank	PER·PBR·ROE 고저 순위 (시장 전체 밸류에이션 스크리닝)	ka10026
get_supply_concentration	매물대집중 종목 — 특정 가격대에 거래가 몰린 종목과 그 구간	ka10025
get_market_movers	신고가/신저가/상한가/하한가/급등/급락/거래량급증/거래량갱신(직전 N일 최대 돌파) 특이 종목	ka10016/17/19/23/24
get_vi_stocks	당일 VI(변동성완화장치) 발동 종목 (발동가·괴리율·시각)	ka10054
get_expected_execution	동시호가 예상체결 순위 (개장 전 08:3009:00 / 마감 전 15:2015:30)	ka10029
get_investor_trend	개인/외국인/기관 순매수 동향 (기간 합계 + 일별)	ka10059, ka10061
get_institution_trend	기관·외국인 추정평균단가 + 일별·기간누적 순매수	ka10045
get_investor_rank	외국인·기관 순매매 상위 종목 / N일 연속 순매수 현황	ka90009, ka10131
get_net_buy_rank	투자자 12주체(개인·외국인·기관계·금융투자·보험·투신·은행·연기금등·사모펀드·기타금융·국가·기타법인)별 순매수 상위 종목 — 직전 완료 거래일 기준	ka10066
get_foreign_intraday	장중 주체별 순매수/순매도 상위 종목 — 외국인·기관계·보험·투신·연기금등·기타법인 (실시간 잠정치)	ka10063, ka10065
get_broker_activity	종목별 거래원(증권사) 매수/매도 상위 5 + 외국계 창구 표시, 전 거래원 50개사 누적 순위(view=broker_rank), 당일 상위에서 이탈한 창구(view=dropout), 또는 시장 전체 외국계 창구 순매매 상위	ka10002, ka10102, ka10037, ka10038, ka10053
get_etf_info	ETF 추적지수·과세유형·시세·NAV/괴리율	ka40002, ka10001, ka40009
get_etf_returns	ETF 기간별 수익률 vs 비교지수(직접 고르는 국내 지수 — 추적지수와 자동으로 맞춰지지 않음) + 일별 NAV·괴리율·추적오차 추이, 일자별 외국인·기관 순매수	ka40001, ka40003, ka40008
get_etf_rank	상장 ETF 전 종목 스크리너 — 괴리율(고평가/저평가)·등락률·거래량·추적오차 정렬 + 과세유형·운용사·추적지수 필터	ka40004
get_short_selling	종목별 일자별 공매도 추이 (공매도량·비중·평균가)	ka10014
get_stock_lending	대차거래 추이 (체결·상환·증감·잔고) — 종목별/시장 전체 + 대차잔고 상위 종목 순위	ka10068, ka20068, ka90012
get_credit_trend	신용융자·대주 잔고 추이 (신규·상환·잔고·공여율·잔고율)	ka10013
get_foreign_holding	외국인 보유(한도) 동향 — 종목별 추이, 또는 시장 전체 순위(한도소진율 증가 / 기간 누적 순매매 / 3일 연속 순매매)	ka10008, ka10036, ka10034, ka10035
get_program_trading	프로그램 매매 상위(당일·날짜 지정) + 추이 (일자별/시간대별/종목별, 코스피/코스닥) + 종목 시간대별·차익거래 잔고	ka90003, ka90004, ka90010, ka90005, ka90013, ka90008, ka90006
get_after_hours	시간외 단일가 (16:00~18:00) — 종목별 5단 호가·시세 또는 등락률 순위	ka10087, ka10098
get_execution_strength	체결강도 추이 (매수÷매도 체결량×100, 100이 균형) — 일별 60거래일 / 시간별 60분	ka10046, ka10047
get_gold_price	KRX 금현물 시세 (금 1Kg / 미니금 100g) — 일별추이 + 기관·개인 순매수, 또는 당일 틱 체결	ka50012, ka50010

관심종목 (영웅문 HTS에 저장한 관심 그룹, 읽기 전용):

Tool	설명	키움 TR
get_watchlist_groups	HTS 관심종목 그룹 목록 (그룹코드+그룹명)	ka01300
get_watchlist	그룹 내 종목 목록 (종목명·전일종가·시장·투자유의 보강)	ka01301, ka10099

키움 REST API에는 관심종목 편집(추가/삭제) TR이 없어 조회만 가능합니다.

테마:

Tool	설명	키움 TR
get_theme_groups	테마 그룹 목록 (등락률·종목수·기간수익률·주요종목; 종목별 편입 테마 검색)	ka90001
get_theme_stocks	특정 테마의 구성종목과 시세 (현재가·등락률·거래량·기간수익률)	ka90002

계좌 (앱키에 귀속된 계좌 기준):

Tool	설명	키움 TR
get_account_balance	예수금 + 총평가금액/총평가손익/추정예탁자산 + 당일/당월/누적 손익, view=settlement은 익일 결제 예정 건별 명세	kt00001, kt00018, kt00004, kt00008
get_account_holdings	보유 종목별 수량/평균단가/현재가/평가손익	kt00018
get_account_today	계좌 당일 현황 — 매매대금·수수료·세금·입출금 + D+2 추정 (실전 전용)	kt00017
get_account_trend	일별 추정예탁자산 추이 + 기간 수익률/평가손익/입출금 요약 (기본 30일, 모의투자 미지원)	kt00002, kt00016
get_transactions	기간별 거래내역 (체결일·단가·정산금액, 모의투자 미지원)	kt00015
get_pending_orders	미체결 주문 (주문번호·구분·상태·주문/미체결수량·주문가격)	ka10075
get_order_executions	체결 내역 (주문번호·구분·상태·주문/체결 수량·가격·수수료+세금, side/종목/주문번호 필터)	ka10076
get_trading_journal	당일매매일지 (종목별 매수/매도 평균가·수량·실현손익, 총손익)	ka10170
calc_isa_tax_status	ISA 손익통산 순이익의 비과세 한도 대비 현황 (확정 + 전량매도 시나리오, kt00015 의존이라 모의투자 미지원)	kt00015, ka10074, kt00018

그 외 ping(연결 확인, 앱키 불필요). 모든 응답은 [모의투자]/[실전투자] 접두어로 어느 서버가 답했는지 표시합니다. search_stock 첫 호출은 종목 마스터(~4,300종목)를 내려받아 몇 초 걸리며 이후 12시간 캐시됩니다.

거래소 기준 — KRX + 넥스트레이드(NXT) 통합

v0.31.0부터 시세·랭킹 tool은 통합(SOR) 기준으로 조회합니다. KRX와 넥스트레이드(NXT) 체결을 합산한 값이며, NXT 거래가능 종목(약 606개, 대형주 다수)은 KRX만 볼 때보다 거래량이 크게 늘어납니다 — 삼성전자 실측(2026-08-03 정규장) KRX 19.2M / NXT 15.5M / 통합 34.7M. KRX만 표시하는 HTS·포털 화면과 숫자가 다르면 대개 이 차이입니다.

예외는 get_after_hours(시간외 단일가) 하나입니다 — 통합 조회가 불가능하며 NXT 거래가능 종목은 애초에 이 TR에서 조회되지 않습니다. 거래원(get_broker_activity)은 v0.47.0에서 통합으로 넘어왔습니다 — 그전까지 KRX 값을 내보내 상위 5의 순위가 실제와 달랐습니다(삼성전자 매수 1위가 KRX 기준 KB증권 / 통합 기준 미래에셋). 호가는 v0.37.0에서 통합으로 넘어왔습니다 — ka10004 대신 ka10007(시세표성정보)을 쓰며, 삼성전자 실측(2026-08-04 정규장) 매수1 잔량이 KRX 18,421 / NXT 17,081 / 통합 36,319이었습니다.

calc_isa_tax_status 사용 메모

• 집계 시작일: .env의 ISA_OPENED_ON(계좌 개설일)이 기본값, 호출 시 from_date로 오버라이드 가능.
• 배당·분배금이 거래내역에서 자동 감지되지 않으면 dividends_received 인자로 수동 입력.
• 종목 과세유형(과세대상 vs 국내주식형)은 자동 분류입니다 — ETF는 키움이 주는 etftxon_type(ka40002)으로 확정하고(조회 실패 시 종목명 휴리스틱으로 폴백), 개별주식 등 그 밖에는 종목명 기반으로 추정합니다. 틀린 경우 overrides: [{stock_code, tax_type}]로 수정. 결과는 참고용 — 실제 과세는 증권사 정산 기준.

요구 사항

• Node.js 22 이상 — Node 20이 2026-04-30에 EOL이 되면서 바닥을 올렸습니다 (process.loadEnvFile은 20.12부터 있으므로 코드가 요구하는 최소치는 그보다 낮습니다)
• 키움증권 REST API 앱키 — 키움 Open API 포털에서 앱 등록 후 발급
  • 모의투자(VIRTUAL)와 실전투자(REAL)는 각각 별도로 발급받은 앱키를 사용하며, 발급받은 키 종류와 KIWOOM_MODE가 일치해야 합니다.
  • 계좌는 앱키에 귀속되므로 계좌번호 입력은 필요 없습니다.

설치

npm에 배포되어 있으므로 클론 없이 npx로 바로 실행할 수 있습니다 — 아래 "Claude Desktop 연결" / "Claude Code 연결"의 npx 설정을 그대로 쓰면 됩니다. 이 경우 앱키는 .env 파일 대신 클라이언트 설정의 env 블록으로 전달합니다(예제는 각 연결 섹션 참고).

소스에서 직접 빌드하거나 코드를 수정하려면:

git clone <이 저장소 URL>   # 또는 소스 복사
cd kiwoom-mcp-server
npm install
cp .env.example .env        # 아래 표를 참고해 값 입력
npm run build               # dist/ 생성
npm test                    # 단위 테스트 (네트워크 불필요)

環境変数（.env）

変数	必須	説明
KIWOOM_APP_KEY	✅	キウム REST API のアプリキー
KIWOOM_APP_SECRET	✅	キウム REST API のアプリシークレット
KIWOOM_MODE		VIRTUAL（模擬投資、デフォルト）または REAL（実取引）
ISA_ENABLED		trueの場合、calc_isa_tax_status ツールを有効にします。デフォルトは false（一般口座基準）です
ISA_TYPE		GENERAL（一般型、上限200万ウォン、デフォルト）または SEOMIN（庶民型／農漁民型、400万ウォン）。ISA_ENABLED=trueの場合のみ使用
ISA_OPENED_ON		ISA口座の開設日 yyyy-MM-dd — calc_isa_tax_status の集計開始日のデフォルト値です。ISA_ENABLED=trueの場合のみ使用
MCP_TRANSPORT		stdio（デフォルト）または http — リモート接続を参照
MCP_AUTH_TOKEN	HTTP モードで必須 ✅	HTTP モードですべての /mcp リクエストに必要な Bearer トークン
MCP_HTTP_PORT		HTTP モードのポート（デフォルトは 8000）
MCP_HTTP_HOST		HTTP モードのバインドアドレス（デフォルトは 127.0.0.1）
MCP_HTTP_NO_AUTH		trueの場合、認証なしでHTTPモードの起動を許可します（非推奨 — 以下のセキュリティ上の注意を参照）
MCP_PUBLIC_URL		HTTP モードで外部に通知するベース URL（例：https://kiwoom.example.com）。未設定の場合は、リクエストの Host と X-Forwarded-Proto から推測します — リバースプロキシがこれらのヘッダーを付与しない場合は、明示的に指定してください

デフォルトは一般（非ISA）口座基準です — 別途設定しない限り、市場・口座照会ツールのみが公開されます。ISA口座を接続して非課税限度額ツールを使用するには、ISA_ENABLED=trueに設定し、ISA_TYPE／ISA_OPENED_ONを入力してください。無効にすると、calc_isa_tax_statusは登録されず、その他のツールはすべてそのまま動作します。

.envはプロジェクトルートで最初に検索されるため、（Claude Desktopのように）任意の作業ディレクトリから実行しても動作します。

Claude Desktop への接続

設定ファイルの場所：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

npx（配布版）— クローンせずに実行します。アプリキーは env ブロックで渡します：

{
  "mcpServers": {
    "kiwoom": {
      "command": "npx",
      "args": ["-y", "kiwoom-mcp-server"],
      "env": {
        "KIWOOM_APP_KEY": "…",
        "KIWOOM_APP_SECRET": "…",
        "KIWOOM_MODE": "REAL"
      }
    }
  }
}

ソースからビルド — dist/index.jsを直接実行します。アプリキーにはプロジェクトルートの .envを使用します：

{
  "mcpServers": {
    "kiwoom": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/절대/경로/kiwoom-mcp-server/dist/index.js"]
    }
  }
}

commandには実行ファイルの絶対パスを指定するのが最も安全です（which node、which npxで確認できます）。GUIアプリはシェルのPATHを継承しないため、"node"／"npx"だけを指定すると、サーバーが何も表示せずに起動しないことがあります — これが最もよくある失敗原因です。

保存後、Claude Desktopを完全に終了して（macOSでは⌘Q）再起動すると、ツールが表示されます。npm run buildで再ビルドした後も、完全に終了してから再起動する必要があります。変更が反映されます。

Claude Code への接続

npx（配布版）— アプリキーは -eフラグで渡します：

claude mcp add kiwoom \
  -e KIWOOM_APP_KEY=… -e KIWOOM_APP_SECRET=… -e KIWOOM_MODE=REAL \
  -- npx -y kiwoom-mcp-server

ソースからビルド — プロジェクトルートの .envを使用します：

claude mcp add kiwoom -- node /절대/경로/kiwoom-mcp-server/dist/index.js

リモート接続（HTTP モード）— claude.ai ウェブ／モバイル

claude.ai（ウェブ／モバイル）のカスタムコネクターは、ローカルのstdioサーバーに直接接続できません。公開HTTPS経由でアクセス可能なStreamable HTTP MCP サーバーが必要です。--httpフラグ（またはMCP_TRANSPORT=http）を指定すると、このサーバーをHTTPモードで起動できます：

MCP_AUTH_TOKEN="$(openssl rand -hex 32)" npx -y kiwoom-mcp-server --http --port 8000
# 엔드포인트: http://127.0.0.1:8000/mcp · 헬스체크: /healthz

• 認証はデフォルトで必須です。 MCP_AUTH_TOKENがない場合、起動を拒否します — すべての /mcpリクエストに Authorization: Bearer <トークン>ヘッダーが必要です。認証なしで公開するには--no-authを明示する必要があります。口座照会ツールがそのまま公開されるため、信頼できるネットワークまたは模擬投資（KIWOOM_MODE=VIRTUAL）でのみ使用してください。
• デフォルトのバインド先は127.0.0.1です — トンネルを前段に配置する構成を前提としています。コンテナー／サーバーに直接公開するには、--host 0.0.0.0を明示してください。
• 公開HTTPS URLは、Cloudflare Tunnelなどで作成します： cloudflared tunnel --url http://localhost:8000（一時URLです — 常時運用には名前付きトンネルを推奨します）。
• OAuthメタデータに含まれるアドレスは、リクエストの HostとX-Forwarded-Protoから推測されます。 Cloudflare Tunnelのようにこれらのヘッダーを付与するプロキシであれば、そのままで構いません。ただし、自分で構築したnginx／CaddyがX-Forwarded-Protoを転送しない場合、issuerがhttp://として通知され、claude.aiが接続を拒否します。その場合はMCP_PUBLIC_URL=https://<ドメイン>を設定してください。
• claude.aiへの登録：Settings → Connectors → Add custom connectorにhttps://<ドメイン>/mcpを入力します（詳細設定のOAuthフィールドは空欄のままにします）。接続時にブラウザーに承認ページが表示され、MCP_AUTH_TOKENの値を接続パスワードとして入力すれば完了です — サーバーにはMCP認証仕様（OAuth 2.0 + PKCE、動的クライアント登録）が組み込まれているため、別途ヘッダーを設定する必要はありません。登録したコネクターはウェブ／モバイル／デスクトップで共通して使用できます。ヘッダーを指定できるクライアント（例：Claude Codeの--header）では、従来どおりAuthorization: Bearer <MCP_AUTH_TOKEN>の静的ヘッダーでも接続できます。 OAuthトークンは作業ディレクトリの.oauth-state.json（0600）に保存されるため、サーバーを再起動しても接続は維持されます。
• ⚠️ キウム API の呼び出しは、このサーバーが実行されている場所から行われます。 REALモードでは、キウム指定端末認証（8050）がIPアドレスに紐付けられているため、登録済みIPアドレス以外の場所（クラウドなど）で実行すると、認証エラーが発生することがあります。リモート公開は、まず模擬投資で確認してください。

既存のstdio動作（Claude Desktop／Codeへの接続）は、引数なしで実行すればこれまでどおりです — ただし、.envまたは環境変数にMCP_TRANSPORT=httpが設定されている場合は例外です。.envはトランスポートを選択する前に読み込まれるため、引数なしで実行してもHTTP経由になり、MCP_AUTH_TOKENがない場合は起動を拒否します。MCP_TRANSPORTの値に関係なくstdioを強制するには、**--stdio**を渡してください。

動作確認

MCPクライアントなしで、stdioを使って直接確認できます：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{}}}' \
  | node dist/index.js

pingは.envがなくても応答します。株価・口座ツールにはアプリキーが必要です。

문제 해결

증상	확인할 것
Desktop에 tool이 안 보임	command가 node 절대 경로인지, npm run build를 했는지, Desktop을 완전 종료 후 재실행했는지
환경설정이 없거나 잘못되었습니다	.env가 프로젝트 루트에 있는지, 필수 변수가 채워졌는지
키움 인증에 실패했습니다	앱키 종류(모의/실전)와 KIWOOM_MODE가 일치하는지, 포털에서 앱이 활성 상태인지
요청 한도를 초과했습니다	키움 레이트리밋(TR당 약 1초 1회). 서버가 자동 재시도한 뒤에도 초과한 경우이니 잠시 후 다시 시도
예수금과 D+2 추정예수금이 다름	미결제(D+2 정산) 매매가 있으면 정상입니다

개발

npm run dev         # tsx로 소스 직접 실행
npm run check       # 버전 5곳 동기화 · 카운트 · README 2종 tool 문서화 · server.ts 등록 누락
npm run check:write # 위 카운트를 실제 값으로 고쳐 씀 (버전은 안 건드림)
npm run typecheck   # tsc --noEmit -p tsconfig.test.json (src + tests)
npm test            # vitest
npm run build       # tsc → dist/

네 가지 모두 CI(.github/workflows/ci.yml, Node 22·24)에서 돌고, 거기에 npm audit --omit=dev --audit-level=high가 한 단계 더 붙습니다. 타입체크가 tsconfig.test.json을 쓰는 이유는 빌드용 tsconfig.json의 rootDir가 src라 테스트를 거기 넣으면 dist/ 레이아웃이 바뀌기 때문입니다 — 빌드는 그대로 tsconfig.json을 씁니다.

구조: src/kiwoom/(인증·HTTP·TR 계층) → src/tools/(MCP tool, 포맷터 분리) → src/isa/(과세유형 분류·실현손익 재구성·손익통산). 상세 규칙과 검증된 API 계약은 CLAUDE.md 참고.

라이선스

MIT