How do I install Kiwoom Securities MCP Server?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Kiwoom Securities MCP Server need an API key?

The publisher lists these environment variables: KIWOOM_APP_KEY, KIWOOM_APP_SECRET, KIWOOM_MODE, ISA_ENABLED.

What transport does Kiwoom Securities MCP Server use?

Kiwoom Securities MCP Server runs locally over stdio.

When was Kiwoom Securities MCP Server last checked?

Last checked 2026-11-09. Read-only MCP server for the Kiwoom Securities REST API: market data, account inquiry, ISA tax tool

Kiwoom Securities 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`

관심종목 (영웅문 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 블록으로 전달:

{
  "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)했다가 다시 실행하면 tool이 보입니다. 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 — 상시 운영은 named tunnel 권장).
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 없이도 응답합니다. 시세·계좌 tool은 앱키가 있어야 합니다.

문제 해결

증상	확인할 것
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

Kiwoom Securities MCP Server

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Kiwoom Securities MCP Server?

Does Kiwoom Securities MCP Server need an API key?

What transport does Kiwoom Securities MCP Server use?

When was Kiwoom Securities MCP Server last checked?

Documentation

kiwoom-mcp-server

제공 Tool

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

`calc_isa_tax_status` 사용 메모

요구 사항

설치

환경 변수 (`.env`)

Claude Desktop 연결

Claude Code 연결

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

동작 확인

문제 해결

개발

라이선스

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Kiwoom Securities MCP Server?

Does Kiwoom Securities MCP Server need an API key?

What transport does Kiwoom Securities MCP Server use?

When was Kiwoom Securities MCP Server last checked?

Documentation

kiwoom-mcp-server

제공 Tool

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

calc_isa_tax_status 사용 메모

요구 사항

설치

환경 변수 (.env)

Claude Desktop 연결

Claude Code 연결

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

동작 확인

문제 해결

개발

라이선스

`calc_isa_tax_status` 사용 메모

환경 변수 (`.env`)