kiwoom-mcp-server
한국어 · English
키움증권 REST API를 조회 전용(read-only) 으로 노출하는 MCP 서버입니다. Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·호가·지수·순위·수급과 내 계좌의 잔고·보유 종목·거래내역을 조회할 수 있고, ISA 계좌라면 비과세 한도 대비 손익통산 현황까지 계산해 줍니다.
⚠️
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
npx -y [email protected]Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
KIWOOM_APP_KEY=<secret> KIWOOM_APP_SECRET=<secret> KIWOOM_MODE=<value> ISA_ENABLED=<value> claude mcp add io.github.chunsam-kiwoom-mcp-server -- npx -y kiwoom-mcp-server@0.52.6รันในเทอร์มินัล
{ "mcpServers": { "io.github.chunsam-kiwoom-mcp-server": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "KIWOOM_APP_KEY": "<secret>", "KIWOOM_APP_SECRET": "<secret>", "KIWOOM_MODE": "<value>", "ISA_ENABLED": "<value>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
한국어 · English
키움증권 REST API를 조회 전용(read-only) 으로 노출하는 MCP 서버입니다. Claude Desktop / Claude Code에서 자연어로 국내 주식 시세·차트·호가·지수·순위·수급과 내 계좌의 잔고·보유 종목·거래내역을 조회할 수 있고, ISA 계좌라면 비과세 한도 대비 손익통산 현황까지 계산해 줍니다.
⚠️
Read-only MCP server for the Kiwoom Securities REST API: market data, account inquiry, ISA tax tool
--no-auth)로는 절대 외부 네트워크에 열지 마세요..env의 AppKey/AppSecret은 실계좌 조회 권한입니다. 절대 커밋하지 마세요
(.gitignore에 이미 등록되어 있습니다).시장 데이터 (계좌와 무관, 앱키만 있으면 사용 가능):
관심종목 (영웅문 HTS에 저장한 관심 그룹, 읽기 전용):
키움 REST API에는 관심종목 편집(추가/삭제) TR이 없어 조회만 가능합니다.
테마:
계좌 (앱키에 귀속된 계좌 기준):
그 외 ping(연결 확인, 앱키 불필요). 모든 응답은 [모의투자]/[실전투자] 접두어로
어느 서버가 답했는지 표시합니다. search_stock 첫 호출은 종목 마스터(~4,300종목)를
내려받아 몇 초 걸리며 이후 12시간 캐시됩니다.
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 인자로 수동 입력.etftxon_type(ka40002)으로 확정하고(조회 실패 시 종목명 휴리스틱으로 폴백), 개별주식 등
그 밖에는 종목명 기반으로 추정합니다. 틀린 경우 overrides: [{stock_code, tax_type}]로
수정. 결과는 참고용 — 실제 과세는 증권사 정산 기준.process.loadEnvFile은 20.12부터 있으므로 코드가 요구하는 최소치는 그보다 낮습니다)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)기본값은 일반(비-ISA) 계좌 기준입니다 — 별도 설정이 없으면 시장·계좌 조회 tool만
노출됩니다. ISA 계좌를 연결해 비과세 한도 tool을 쓰려면 ISA_ENABLED=true로 켜고
ISA_TYPE/ISA_OPENED_ON을 채우세요. 끄면 calc_isa_tax_status가 등록되지 않고
나머지 tool은 모두 그대로 동작합니다.
.env는 프로젝트 루트에서 먼저 찾기 때문에 (Claude Desktop처럼) 임의의 작업
디렉터리에서 실행돼도 동작합니다.
설정 파일 위치:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonnpx (배포판) — 클론 없이 실행. 앱키는 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로 다시 빌드한 뒤에도 완전 종료 후 재실행해야
변경이 반영됩니다.
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
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을 명시하세요.cloudflared tunnel --url http://localhost:8000 (임시 URL — 상시 운영은 named tunnel 권장).Host와 X-Forwarded-Proto에서 추론합니다.
Cloudflare Tunnel처럼 그 헤더를 붙여 주는 프록시라면 그대로 두면 되지만, 직접 세운
nginx/Caddy가 X-Forwarded-Proto를 넘기지 않으면 issuer가 http://로 광고되어
claude.ai가 연결을 거부합니다. 그럴 때 MCP_PUBLIC_URL=https://<도메인>으로 고정하세요.https://<도메인>/mcp를 입력합니다 (고급 설정의 OAuth 필드는 비워둡니다). 연결 시
브라우저에 승인 페이지가 뜨고, MCP_AUTH_TOKEN 값을 접속 암호로 입력하면
완료됩니다 — 서버가 MCP 인증 스펙(OAuth 2.0 + PKCE, 동적 클라이언트 등록)을 내장하고
있어 별도 헤더 설정이 필요 없습니다. 등록한 커넥터는 웹/모바일/데스크톱에서 공용입니다.
헤더를 지정할 수 있는 클라이언트(예: Claude Code --header)는 기존처럼
Authorization: Bearer <MCP_AUTH_TOKEN> 정적 헤더로도 접속할 수 있습니다.
OAuth 토큰은 작업 디렉터리의 .oauth-state.json(0600)에 저장되어 서버를 재시작해도
연결이 유지됩니다.기존 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은 앱키가 있어야 합니다.
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 참고.
Read-only MCP server for the Kiwoom Securities REST API: market data, account inquiry, ISA tax tool
{ "mcpServers": { "io.github.chunsam-kiwoom-mcp-server": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "KIWOOM_APP_KEY": "<secret>", "KIWOOM_APP_SECRET": "<secret>", "KIWOOM_MODE": "<value>", "ISA_ENABLED": "<value>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: KIWOOM_APP_KEY, KIWOOM_APP_SECRET, KIWOOM_MODE, ISA_ENABLED
Kiwoom Securities MCP Server ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-09 Read-only MCP server for the Kiwoom Securities REST API: market data, account inquiry, ISA tax tool