Kiwoom Securities MCP Server

Read-only MCP server for the Kiwoom Securities REST API: market data, account inquiry, ISA tax tool

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "kiwoom-securities-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "kiwoom-mcp-server"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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:30~~09:00 / 마감 전 15:20~~15: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` tool 활성화. 기본값 `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) 계좌 기준입니다 — 별도 설정이 없으면 시장·계좌 조회 tool만 노출됩니다. ISA 계좌를 연결해 비과세 한도 tool을 쓰려면 ISA_ENABLED=true로 켜고 ISA_TYPE/ISA_OPENED_ON을 채우세요. 끄면 calc_isa_tax_status가 등록되지 않고 나머지 tool은 모두 그대로 동작합니다.

.env는 프로젝트 루트에서 먼저 찾기 때문에 (Claude Desktop처럼) 임의의 작업 디렉터리에서 실행돼도 동작합니다.

Claude Desktop 연결

설정 파일 위치:

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

npx (배포판) — 클론 없이 실행. 앱키는 env 블록으로 전달:

config.json

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

소스 빌드 — dist/index.js 직접 실행. 앱키는 프로젝트 루트 .env 사용:

config.json

{
  "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)했다가 다시 실행하면 tool이 보입니다. npm run build로 다시 빌드한 뒤에도 완전 종료 후 재실행해야 변경이 반영됩니다.

Claude Code 연결

npx (배포판) — 앱키는 -e 플래그로 전달:

Terminal

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

소스 빌드 — 프로젝트 루트 .env 사용:

Terminal

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

원격 연결 (HTTP 모드) — claude.ai 웹/모바일

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars

Stargazers on the source repository.

Last commit

11d ago

Most recent push to the default branch.

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Kiwoom Securities MCP Server

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "kiwoom-securities-mcp-server": { "command": "npx", "args": ["-y","kiwoom-mcp-server"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Kiwoom Securities MCP Server AllMCPs Directory Badge

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/kiwoom-securities-mcp-server?style=directory)](https://allmcps.com/mcp/kiwoom-securities-mcp-server)

HTML Embed

<a href="https://allmcps.com/mcp/kiwoom-securities-mcp-server"><img src="https://allmcps.com/api/badge/kiwoom-securities-mcp-server?style=directory" alt="Kiwoom Securities MCP Server on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

15/15 checks healthy over the last 46d

40Quality signal: Fair · 40/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools16/30

Adoption & activity4/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 3d ago via OSV.dev · kiwoom-mcp-server (npm)

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Kiwoom Securities MCP Server →Install in Claude Desktop Install in Cursor Install in VS Code Setup guides for all 13 MCP clients

Kiwoom Securities MCP Server

Read-only MCP server for the Kiwoom Securities REST API: market data, account inquiry, ISA tax tool

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "kiwoom-securities-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "kiwoom-mcp-server"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

kiwoom-mcp-server

한국어 · English

⚠️ 보안 경고

기본 실행은 로컬 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:30~~09:00 / 마감 전 15:20~~15: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

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

`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가 일치해야 합니다.
- 계좌는 앱키에 귀속되므로 계좌번호 입력은 필요 없습니다.

설치

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

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` tool 활성화. 기본값 `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`로 추론 — 리버스 프록시가 그 헤더를 붙이지 않으면 명시해야 합니다

.env는 프로젝트 루트에서 먼저 찾기 때문에 (Claude Desktop처럼) 임의의 작업 디렉터리에서 실행돼도 동작합니다.

Claude Desktop 연결

설정 파일 위치:

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

npx (배포판) — 클론 없이 실행. 앱키는 env 블록으로 전달:

config.json

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

소스 빌드 — dist/index.js 직접 실행. 앱키는 프로젝트 루트 .env 사용:

config.json

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

command에는 실행 파일의 절대 경로를 쓰는 편이 가장 안전합니다 (which node, which npx로 확인). GUI 앱은 셸 PATH를 상속받지 않으므로 "node"/"npx"라고만 쓰면 서버가 조용히 뜨지 않을 수 있습니다 — 가장 흔한 실패 원인입니다.

Claude Code 연결

npx (배포판) — 앱키는 -e 플래그로 전달:

Terminal

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

소스 빌드 — 프로젝트 루트 .env 사용:

Terminal

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

원격 연결 (HTTP 모드) — claude.ai 웹/모바일

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars

Stargazers on the source repository.

Last commit

11d ago

Most recent push to the default branch.

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Kiwoom Securities MCP Server

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "kiwoom-securities-mcp-server": { "command": "npx", "args": ["-y","kiwoom-mcp-server"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/kiwoom-securities-mcp-server?style=directory)](https://allmcps.com/mcp/kiwoom-securities-mcp-server)

HTML Embed

<a href="https://allmcps.com/mcp/kiwoom-securities-mcp-server"><img src="https://allmcps.com/api/badge/kiwoom-securities-mcp-server?style=directory" alt="Kiwoom Securities MCP Server on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

15/15 checks healthy over the last 46d

40Quality signal: Fair · 40/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools16/30

Adoption & activity4/15

Community engagement0/10

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 3d ago via OSV.dev · kiwoom-mcp-server (npm)

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Kiwoom Securities MCP Server

Quick Install

Client Config & Setup

Documentation Overview

kiwoom-mcp-server

제공 Tool

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

calc_isa_tax_status 사용 메모

요구 사항

설치

환경 변수 (.env)

Claude Desktop 연결

Claude Code 연결

원격 연결 (HTTP 모드) — claude.ai 웹/모바일

Related MCP Servers

Adoption & maintenance

Reviews

Frequently Asked Questions about Kiwoom Securities MCP Server

AllMCPs Directory Badge

Technical Specs & Signals

Supply-chain signal

Feature Your MCP Server

Own this project?

Share & Embed

Explore more

Kiwoom Securities MCP Server

Quick Install

Client Config & Setup

Documentation Overview

kiwoom-mcp-server

제공 Tool

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

calc_isa_tax_status 사용 메모

요구 사항

설치

환경 변수 (.env)

Claude Desktop 연결

Claude Code 연결

원격 연결 (HTTP 모드) — claude.ai 웹/모바일

Related MCP Servers

Adoption & maintenance

Reviews

Frequently Asked Questions about Kiwoom Securities MCP Server

AllMCPs Directory Badge

Technical Specs & Signals

Supply-chain signal

Feature Your MCP Server

Own this project?

Share & Embed

Explore more

`calc_isa_tax_status` 사용 메모

환경 변수 (`.env`)

`calc_isa_tax_status` 사용 메모

환경 변수 (`.env`)