kiwoom-mcp-server

한국어 · English

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

⚠️ 보안 경고

• 이 서버는 로컬에서만 실행하고 절대 외부 네트워크에 노출하지 마세요.

• .env의 AppKey/AppSecret은 실계좌 조회 권한입니다. 절대 커밋하지 마세요 (.gitignore에 이미 등록되어 있습니다).

• 주문(매수/매도/정정/취소) 기능은 설계상 제외되어 있습니다. 이 서버가 계좌를 변경하는 일은 없습니다.

제공 Tool

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

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

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

테마:

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

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

calc_isa_tax_status 사용 메모

• 집계 시작일: .env의 ISA_OPENED_ON(계좌 개설일)이 기본값, 호출 시 from_date로 오버라이드 가능.

• 배당·분배금이 거래내역에서 자동 감지되지 않으면 dividends_received 인자로 수동 입력.

• 종목 과세유형(과세대상 vs 국내주식형)은 종목명 기반 자동 분류이며, 틀린 경우 overrides: [{stock_code, tax_type}]로 수정. 결과는 참고용 — 실제 과세는 증권사 정산 기준.

Related MCP server: kiwoom-mcp

요구 사항

• Node.js 20.12 이상 (process.loadEnvFile 사용)

• 키움증권 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)

기본값은 일반(비-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

동작 확인

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 typecheck  # tsc --noEmit
npm test           # vitest
npm run build      # tsc → dist/

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

라이선스

MIT