kiwoom-mcp

키움증권 REST API를 Model Context Protocol (MCP) 도구로 래핑한 서버입니다. Claude Code 등 MCP를 지원하는 LLM 클라이언트에서 한국 주식 정보를 직접 조회할 수 있습니다.

현재 버전은 조회 전용입니다. 주문(매수/매도/취소) 기능은 포함되어 있지 않습니다.

---

면책 조항 (Disclaimer)

이 소프트웨어를 사용함으로써 발생하는 모든 결과에 대한 책임은 전적으로 사용자 본인에게 있습니다.

• 이 프로젝트는 개인 학습 및 편의 목적으로 제작되었으며, 키움증권의 공식 제품이 아닙니다.
• 투자 조언, 매매 권유, 또는 수익 보장을 하지 않습니다.
• API 호출로 인한 과금, 데이터 오류, 계좌 정보 노출, 토큰 유출 등 어떠한 직접적·간접적 손해에 대해서도 제작자는 책임지지 않습니다.
• 키움증권 OpenAPI 이용 약관을 반드시 확인하고, 본인의 책임 하에 사용하세요.
• API 키와 시크릿 키는 절대 공개 저장소에 커밋하지 마세요. 환경변수 또는 .env 파일로 관리하세요.
• 이 도구를 통해 조회한 데이터의 정확성을 보장하지 않습니다. 실제 투자 판단은 반드시 공식 HTS/MTS를 통해 확인하세요.

---

사전 준비

1. 키움증권 OpenAPI 신청: 키움 OpenAPI 포털에서 REST API 사용 신청
2. App Key / Secret Key 발급: OpenAPI 포털에서 발급
3. Node.js 18+ 설치

---

제공 도구

도구명	설명	입력 파라미터
get_stock_price	현재가 조회 (종목명, 등락률, PER, PBR 등)	stockCode (6자리)
get_orderbook	호가 조회 (매도/매수 1~10호가, 잔량)	stockCode
get_daily_chart	일봉 차트 (시/고/저/종가, 거래량)	stockCode, baseDate? (YYYYMMDD)
get_investor_trend	투자자별 매매동향 (외국인/기관/개인 순매수)	stockCode
get_account_balance	계좌평가현황 (예수금, 보유종목, 손익률)	없음
get_deposit	예수금 상세 조회 (출금가능, 주문가능금액)	없음
get_unfilled_orders	미체결 주문 조회	없음
get_filled_orders	체결 내역 조회	stockCode? (미입력 시 전체)

---

설치

git clone https://github.com/java-jaydev/kiwoom-mcp.git
cd kiwoom-mcp
pnpm install
pnpm run build

pnpm이 없으면 npm install && npm run build로도 가능합니다.

---

환경변수

변수명	필수	설명
KIWOOM_APP_KEY	O	키움 OpenAPI App Key
KIWOOM_SECRET_KEY	O	키움 OpenAPI Secret Key
KIWOOM_API_BASE_URL	X	API 베이스 URL (기본값: https://api.kiwoom.com)

---

Claude Code 연동

방법 1: CLI 명령어 (권장)

claude mcp add --transport stdio --scope user kiwoom \
  --env KIWOOM_APP_KEY=<your-app-key> \
  --env KIWOOM_SECRET_KEY=<your-secret-key> \
  -- node /path/to/kiwoom-mcp/dist/index.js

방법 2: .mcp.json (프로젝트 스코프)

프로젝트 루트에 .mcp.json 생성:

{
  "mcpServers": {
    "kiwoom": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/kiwoom-mcp/dist/index.js"],
      "env": {
        "KIWOOM_APP_KEY": "<your-app-key>",
        "KIWOOM_SECRET_KEY": "<your-secret-key>"
      }
    }
  }
}

.mcp.json에 API 키가 포함되므로 반드시 .gitignore에 추가하세요.

설정 후 Claude Code를 재시작하고 /mcp 명령어로 서버 연결을 확인합니다.

---

검증

# MCP Inspector로 로컬 테스트
npx @modelcontextprotocol/inspector node dist/index.js

# Claude Code에서 연동 확인
# /mcp 명령어로 서버 상태 확인 후 "삼성전자 현재가 알려줘" 등 질의

---

주의사항

• IP 제한: 키움 API 토큰은 발급된 IP에서만 유효합니다. 서버와 클라이언트가 같은 IP에서 실행되어야 합니다.
• 토큰 관리: 토큰 유효기간 24시간, 만료 1시간 전 자동 갱신됩니다.
• 장 운영시간: 장 마감 후에는 시가/고가/저가가 0으로 반환될 수 있습니다.
• 가격 부호: 키움 API 응답의 가격에는 +/- 부호가 붙으며, 현재가 등은 절대값으로 변환하여 반환합니다.
• Rate Limit: 키움 API의 호출 제한을 준수하세요. 과도한 호출은 차단될 수 있습니다.

---

기술 스택

• TypeScript + Node.js (ES Module)
• @modelcontextprotocol/sdk
• Zod (입력 검증)
• Stdio Transport

---

라이선스

MIT License

---

기여

이슈와 PR을 환영합니다. 단, API 키나 시크릿 키가 포함된 커밋은 절대 하지 마세요.