GoogleAIBuilder/KisStock0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ae11528dd946c92fcf8274960264f27eb8892e4f
KisStock0/한국투자증권(API)/MCP/Kis Trading MCP/Readme.md
LGram16 ae11528dd9 initial commit
2026-02-04 00:16:34 +09:00

12 KiB
Raw Blame History

중요 : MCP에 대한 내용을 완전히 숙지하신 뒤 사용해 주십시오.

이 프로그램을 실행하여 발생한 모든 책임은 사용자 본인에게 있습니다.

한국투자증권 OPEN API MCP 서버 - Docker 설치 가이드

한국투자증권의 다양한 금융 API를 Docker를 통해 Claude Desktop에서 쉽게 사용할 수 있도록 하는 설치 가이드입니다.

🚀 주요 기능

지원하는 API 카테고리

카테고리 개수 주요 기능
국내주식 74개 현재가, 호가, 차트, 잔고, 주문, 순위분석, 시세분석, 종목정보, 실시간시세 등
해외주식 34개 미국/아시아 주식 시세, 잔고, 주문, 체결내역, 거래량순위, 권리종합 등
국내선물옵션 20개 선물옵션 시세, 호가, 차트, 잔고, 주문, 야간거래, 실시간체결 등
해외선물옵션 19개 해외선물 시세, 주문내역, 증거금, 체결추이, 옵션호가 등
국내채권 14개 채권 시세, 호가, 발행정보, 잔고조회, 주문체결내역 등
ETF/ETN 2개 NAV 비교추이, 현재가 등
ELW 1개 ELW 거래량순위

전체 API 총합계: 166개

핵심 특징

  • 🐳 Docker 컨테이너화: 완전 격리된 환경에서 안전한 실행
  • ⚡ 동적 코드 실행: GitHub에서 실시간으로 API 코드를 다운로드하여 실행
  • 🔧 설정 기반: JSON 파일로 API 설정 및 파라미터 관리
  • 🛡️ 안전한 실행: 격리된 임시 환경에서 코드 실행
  • 🔍 검증 기능: API 상세 정보 조회로 파라미터 확인
  • 🌍 환경 지원: 실전/모의 환경 구분 지원
  • 🔐 자동 설정: 서버 시작 시 KIS 인증 설정 자동 생성
  • 🖥️ 크로스 플랫폼: Windows, macOS, Linux 모두 지원

📦 Docker 설치 및 설정

📋 Docker 설치

🚀 빠른 설치 (권장)

공식 Docker Desktop을 사용하세요:

📋 OS별 간단 가이드

🍎 macOS
# Homebrew 사용 (권장)
brew install --cask docker

# 또는 공식 인스톨러 다운로드
# https://www.docker.com/products/docker-desktop/
🐧 Linux (Ubuntu/Debian)
# 공식 스크립트 사용 (권장)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER
🪟 Windows

⚠️ Windows는 추가 설정이 필요합니다:

  1. 시스템 요구사항 확인

    • Windows 10/11 Pro, Enterprise, Education
    • WSL2 또는 Hyper-V 지원

  2. Docker Desktop 설치

    • 공식 사이트에서 다운로드
    • 설치 중 "Use WSL 2" 옵션 선택 권장

  3. 설치 후 확인

    docker --version
docker run hello-world

Windows 상세 설치 가이드: Docker 공식 문서 참조

요구사항

  • Docker 20.10+
  • 한국투자증권 OPEN API 계정

📋 설치 및 설정 단계

1단계: 프로젝트 클론

# 프로젝트 클론
git clone https://github.com/koreainvestment/open-trading-api.git
cd "open-trading-api/MCP/Kis Trading MCP"

2단계: 한국투자증권 API 정보 준비

한국투자증권 개발자 센터에서 발급받은 정보를 준비하세요:

필수 정보:

  • App Key (실전용)
  • App Secret (실전용)
  • 계좌 정보들

선택 정보:

  • App Key (모의용)
  • App Secret (모의용)

3단계: Docker 이미지 빌드

# Docker 이미지 빌드
docker build -t kis-trade-mcp .

# 또는 태그와 함께 빌드
docker build -t kis-trade-mcp:latest .

4단계: Docker 컨테이너 실행

기본 실행:

docker run -d \
  --name kis-trade-mcp \
  -p 3000:3000 \
  -e KIS_APP_KEY="your_app_key" \
  -e KIS_APP_SECRET="your_app_secret" \
  -e KIS_PAPER_APP_KEY="your_paper_app_key" \
  -e KIS_PAPER_APP_SECRET="your_paper_app_secret" \
  -e KIS_HTS_ID="your_hts_id" \
  -e KIS_ACCT_STOCK="12345678" \
  -e KIS_ACCT_FUTURE="87654321" \
  -e KIS_PAPER_STOCK="11111111" \
  -e KIS_PAPER_FUTURE="22222222" \
  -e KIS_PROD_TYPE="01" \
  kis-trade-mcp

5단계: 컨테이너 상태 확인

# 컨테이너 상태 확인
docker ps

# 컨테이너 로그 확인
docker logs kis-trade-mcp

# 실시간 로그 확인
docker logs -f kis-trade-mcp

# HTTP 서버 접근 확인
curl http://localhost:3000/sse

6단계: HTTP 서버 접근 확인

컨테이너가 정상적으로 실행되면 HTTP 서버에 접근할 수 있습니다:

# 서버 상태 확인
curl http://localhost:3000/sse

# 또는 브라우저에서 접근
# http://localhost:3000/sse

🔗 Claude Desktop 연동 및 설정

📝 Claude Desktop 설정

Claude Desktop 설정 파일에 MCP 서버를 등록하세요.

설정 파일 위치:

  • Linux/Mac: ~/.claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

🐧 Linux/Mac 설정

{
  "mcpServers": {
    "kis-trade-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/sse"]
    }
  }
}

🪟 Windows 설정

{
  "mcpServers": {
    "kis-trade-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/sse"]
    }
  }
}

💬 사용법 및 질문 예시

기본 사용 패턴

  1. 종목 검색: 먼저 종목 코드를 찾습니다
  2. API 확인: 사용할 API의 파라미터를 확인합니다
  3. API 호출: 필요한 파라미터와 함께 API를 호출합니다

질문 예시

주식 시세 조회:

  • "삼성전자(005930) 현재가 시세 조회해줘"
  • "애플(AAPL) 해외주식 현재 체결가 알려줘"
  • "삼성전자 종목코드 찾아줘"

잔고 및 계좌:

  • "국내주식 잔고 조회해줘"
  • "해외주식 잔고 확인해줘"

채권 및 기타:

  • "국고채 3년물 호가 정보 조회하는 방법"
  • "KODEX 200 ETF(069500) NAV 비교추이 확인해줘"

모의투자:

  • "모의투자로 삼성전자 현재가 조회해줘"
  • "데모 환경에서 애플 주식 시세 알려줘"

🔧 컨테이너 관리

컨테이너 제어

# 컨테이너 시작
docker start kis-trade-mcp

# 컨테이너 중지
docker stop kis-trade-mcp

# 컨테이너 재시작
docker restart kis-trade-mcp

# 컨테이너 제거
docker stop kis-trade-mcp
docker rm kis-trade-mcp

컨테이너 내부 접근

# 컨테이너 내부 bash 실행
docker exec -it kis-trade-mcp /bin/bash

# 환경변수 확인
docker exec kis-trade-mcp env | grep KIS

# 로그 실시간 확인
docker logs -f kis-trade-mcp

💡 사용 팁

  1. 환경변수 관리: 민감한 정보는 환경변수로 안전하게 관리
  2. 로그 모니터링: docker logs -f로 실시간 로그 확인
  3. 리소스 모니터링: docker stats로 컨테이너 리소스 사용량 확인
  4. 백업 전략: 중요한 설정 파일은 정기적으로 백업
  5. 보안 관리: 컨테이너 내부에서만 민감한 정보 처리

📝 로깅 및 모니터링

로그 확인

# 전체 로그
docker logs kis-trade-mcp

# 최근 100줄
docker logs --tail 100 kis-trade-mcp

# 실시간 로그
docker logs -f kis-trade-mcp

# 특정 시간대 로그
docker logs --since "2024-01-01T00:00:00" kis-trade-mcp

성능 모니터링

# 컨테이너 리소스 사용량
docker stats kis-trade-mcp

# 컨테이너 상세 정보
docker inspect kis-trade-mcp

# 프로세스 확인
docker exec kis-trade-mcp ps aux

🛠️ 문제 해결

일반적인 문제들

1. 컨테이너가 시작되지 않는 경우

# 로그 확인
docker logs kis-trade-mcp

# 환경변수 확인
docker exec kis-trade-mcp env | grep KIS

2. 환경변수 누락

# 컨테이너 재시작
docker restart kis-trade-mcp

# 환경변수 다시 설정하여 실행
docker run -d --name kis-trade-mcp -e KIS_APP_KEY="..." ...

3. 메모리 부족

# 메모리 사용량 확인
docker stats kis-trade-mcp

# 컨테이너 리소스 제한 설정
docker run -d --name kis-trade-mcp --memory="2g" --cpus="2" ...

4. 네트워크 연결 문제

# 포트 확인
docker port kis-trade-mcp

# 네트워크 연결 테스트
curl http://localhost:3000/sse

디버깅 명령어

# 컨테이너 내부 bash 접근
docker exec -it kis-trade-mcp /bin/bash

# Python 환경 확인
docker exec kis-trade-mcp uv run python -c "import sys; print(sys.path)"

# 의존성 확인
docker exec kis-trade-mcp uv pip list

# 네트워크 연결 확인
docker exec kis-trade-mcp ping github.com

🔒 보안 고려사항

  • 컨테이너 격리: 호스트 시스템과 완전히 분리된 환경에서 실행
  • 환경변수 보안: 민감한 정보는 환경변수로 전달, 코드에 하드코딩 금지
  • 임시 파일 정리: 각 API 호출 후 임시 파일 자동 삭제
  • 네트워크 격리: 필요한 경우 Docker 네트워크를 통한 추가 격리

⚠️ 제한사항 및 성능

API 호출 제한

  • 한국투자증권 API의 호출 제한을 준수해야 합니다
  • 분당 호출 횟수 제한이 있을 수 있습니다
  • 실전 환경에서는 더욱 신중한 사용이 필요합니다

Docker 성능 고려사항

  • 컨테이너 오버헤드: Docker 컨테이너 실행으로 인한 약간의 성능 오버헤드
  • 메모리 사용량: SQLAlchemy와 pandas가 메모리를 많이 사용할 수 있음
  • 네트워크 지연: GitHub 다운로드 시 네트워크 지연 발생

다단계 타임아웃 설정

  • 파일 다운로드: 30초 (GitHub 응답 대기)
  • 코드 실행: 15초 (API 호출 및 결과 처리)
  • 컨테이너 시작: 60초 (의존성 설치 및 초기화)

🔗 관련 링크

주의: 이 프로젝트는 한국투자증권 OPEN API를 사용합니다. 사용 전 반드시 한국투자증권 개발자 센터에서 API 이용약관을 확인하시기 바랍니다.

⚠️ 투자 책임 고지

본 MCP 서버는 한국투자증권 OPEN API를 활용한 도구일 뿐이며, 투자 조언이나 권유를 제공하지 않습니다.

  • 📈 투자 결정 책임: 모든 투자 결정과 그에 따른 손익은 전적으로 투자자 본인의 책임입니다
  • 💰 손실 위험: 주식, 선물, 옵션 등 모든 금융상품 투자에는 원금 손실 위험이 있습니다
  • 🔍 정보 검증: API를 통해 제공되는 정보의 정확성은 한국투자증권에 의존하며, 투자 전 반드시 정보를 검증하시기 바랍니다
  • 🧠 신중한 판단: 충분한 조사와 신중한 판단 없이 투자하지 마시기 바랍니다
  • 🎯 모의투자 권장: 실전 투자 전 반드시 모의투자를 통해 충분히 연습하시기 바랍니다

투자는 본인의 판단과 책임 하에 이루어져야 하며, 본 도구 사용으로 인한 어떠한 손실에 대해서도 개발자는 책임지지 않습니다.

Reference in New Issue View Git Blame Copy Permalink