한국투자증권 KIS MCP Server

한국투자증권 Open API를 Claude에서 직접 사용할 수 있는 MCP 서버입니다.

사전 준비

1. KIS Developers 에서 앱키/앱시크리트 발급
2. Node.js 22+ 및 npm 설치

환경변수 설정

# 실전투자 (필수)
export KIS_APP_KEY="your_app_key"
export KIS_APP_SECRET="your_app_secret"
export KIS_ACCOUNT_NO="12345678"     # 계좌번호 앞 8자리
export KIS_ACCOUNT_PROD="01"         # 계좌상품코드 (기본값: 01)

# 모의투자 (선택)
export KIS_PAPER_APP_KEY="your_paper_app_key"
export KIS_PAPER_APP_SECRET="your_paper_app_secret"
export KIS_PAPER_ACCOUNT_NO="12345678"

빌드 및 실행

npm install
npm run build

Claude Code 설정 (.mcp.json)

프로젝트 루트 또는 ~/.claude/ 에 추가:

{
  "mcpServers": {
    "kis": {
      "command": "node",
      "args": ["/path/to/koreainvestment-mcp/dist/index.js"],
      "env": {
        "KIS_APP_KEY": "your_app_key",
        "KIS_APP_SECRET": "your_app_secret",
        "KIS_ACCOUNT_NO": "12345678",
        "KIS_PAPER_APP_KEY": "your_paper_app_key",
        "KIS_PAPER_APP_SECRET": "your_paper_app_secret",
        "KIS_PAPER_ACCOUNT_NO": "12345678"
      }
    }
  }
}

개발 중에는 tsx로 직접 실행 가능:

{
  "mcpServers": {
    "kis": {
      "command": "npx",
      "args": ["tsx", "/path/to/koreainvestment-mcp/src/index.ts"],
      "env": { "...": "..." }
    }
  }
}

제공 도구 (12개)

도구	설명	읽기전용
kis_get_domestic_stock_price	국내주식 현재가 조회	✅
kis_get_domestic_stock_chart	국내주식 일/주/월별 시세	✅
kis_get_domestic_balance	국내주식 잔고 조회	✅
kis_get_account_assets	투자계좌 자산 현황 (실전 전용)	✅
kis_place_domestic_order	국내주식 현금 주문	❌
kis_revise_or_cancel_domestic_order	국내주식 주문 정정/취소	❌
kis_get_overseas_stock_price	해외주식 현재가 조회	✅
kis_get_overseas_stock_chart	해외주식 일/주/월별 시세	✅
kis_get_overseas_balance	해외주식 잔고 조회	✅
kis_place_overseas_order	해외주식 주문	❌
kis_search_stock	종목코드·종목명 검색	✅
kis_master_status	종목 마스터 DB 현황	✅

주의사항

• env="real" 주문 도구는 실제 자금이 사용됩니다. 테스트는 반드시 env="demo"를 사용하세요.
• 주문 도구의 기본값은 env="demo"(모의투자)로 설정되어 있습니다.
• 실전투자와 모의투자의 앱키/계좌번호는 별개입니다.
• 토큰은 프로세스 메모리에 캐시되며 만료 5분 전에 자동 재발급됩니다.
• 종목 마스터 데이터는 ~/.kis_mcp/master.db에 저장되며 하루 1회 자동 갱신됩니다.