kiwoom-mcp

Claude Desktop에서 자연어로 키움증권 계좌를 제어하는 MCP 서버

키움증권 REST API와 Claude Desktop을 MCP(Model Context Protocol)로 연결하여, 자연어로 주식 조회/매매를 할 수 있습니다.

사용자: "삼성전자 현재가 알려줘"
Claude: 삼성전자(005930) 현재가 72,300원, 전일대비 +1,200원(+1.69%)...

사용자: "10주 시장가 매수해줘"
Claude: 삼성전자 10주 시장가 매수 주문 완료 (주문번호: 12345)

사전 준비

1. openapi.kiwoom.com → 로그인 → API 사용신청
2. 계좌 등록 + 본인 서버 IP 등록 (필수)
3. App Key 다운로드
4. 모의투자 신청 (kiwoom.com → 모의/실전투자 → 상시모의투자)

설치 방법

방법 1: 로컬 설치 (stdio)

git clone https://github.com/YOUR_USERNAME/kiwoom-mcp.git
cd kiwoom-mcp
npm install
npm run build

Claude Desktop 설정

설정 파일 위치:

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

{
  "mcpServers": {
    "kiwoom": {
      "command": "node",
      "args": ["/절대경로/kiwoom-mcp/dist/index.js"],
      "env": {
        "KIWOOM_APP_KEY": "...",
        "KIWOOM_SECRET_KEY": "...",
        "KIWOOM_ACCOUNT_NO": "계좌번호10자리",
        "KIWOOM_IS_MOCK": "true"
      }
    }
  }
}

빌드 없이 개발 중 실행하려면:

"command": "npx", "args": ["tsx", "/경로/kiwoom-mcp/src/index.ts"]

방법 2: Docker 원격 배포 (HTTP)

키움 API는 등록된 IP에서만 호출 가능하므로, IP가 등록된 서버에 Docker로 배포하고 원격으로 연결할 수 있습니다.

1. 서버에 .env 파일 생성

KIWOOM_APP_KEY=발급받은_앱키
KIWOOM_SECRET_KEY=발급받은_시크릿키
KIWOOM_ACCOUNT_NO=계좌번호10자리
KIWOOM_IS_MOCK=true
MCP_TRANSPORT=http
MCP_PORT=3000

2. Docker Compose로 실행

git clone https://github.com/YOUR_USERNAME/kiwoom-mcp.git
cd kiwoom-mcp
# .env 파일을 위에서 생성한 내용으로 작성
docker compose up -d --build

3. Claude Desktop에서 원격 연결

{
  "mcpServers": {
    "kiwoom": {
      "url": "http://서버IP:3000/mcp"
    }
  }
}

환경변수

| 변수 | 필수 | 설명 | |------|------|------| | KIWOOM_APP_KEY | O | 키움 OpenAPI 앱 키 | | KIWOOM_SECRET_KEY | O | 키움 OpenAPI 시크릿 키 | | KIWOOM_ACCOUNT_NO | O | 계좌번호 (10자리) | | KIWOOM_IS_MOCK | O | 모의투자 여부 (true / false) | | MCP_TRANSPORT | X | 전송 방식 (stdio 또는 http, 기본값: stdio) | | MCP_PORT | X | HTTP 모드 포트 (기본값: 3000) |

제공 도구 (12개)

잔고/포트폴리오

| Tool | 설명 | |------|------| | get_account_balance | 보유 주식 목록, 평가금액, 수익률 | | get_portfolio_summary | 종목별 비중/손익 분석 | | get_deposit_detail | 예수금, 출금/주문 가능금액 |

시세 조회

| Tool | 설명 | |------|------| | get_stock_price | 현재가, 등락률, 거래량, PER/PBR | | get_stock_chart | 일봉 OHLCV 차트 (기간 지정) | | search_stock_code | 종목명 → 종목코드 검색 |

주문

| Tool | 설명 | |------|------| | place_buy_order | 시장가/지정가 매수 | | place_sell_order | 시장가/지정가 매도 | | get_unfilled_orders | 미체결 주문 목록 | | cancel_order | 주문 취소 |

거래내역 분석

| Tool | 설명 | |------|------| | get_trade_history | 기간별 체결내역 | | analyze_profit_loss | 종목별 실현손익, 승률 분석 |

사용 예시

"오늘 내 포트폴리오 현황 분석해줘"
"HD현대일렉트릭 현재가 알려주고 10주 매수해줘"
"이번달 거래 손익 분석해줘"
"미체결 주문 전부 취소해줘"

주의사항

• 반드시 모의투자(KIWOOM_IS_MOCK=true)에서 충분히 테스트한 후 실전 전환하세요
• API 키를 공개 저장소에 절대 업로드하지 마세요
• 키움 REST API는 허용된 IP에서만 동작합니다
• 본 프로젝트는 키움증권 공식 프로젝트가 아닙니다
• 투자 손실에 대한 책임은 사용자 본인에게 있습니다

라이선스

MIT - 투자 손실에 대한 책임은 지지 않습니다.