KisStock/한국투자증권(API)/MCP/MCP AI 도구 연결 방법.md

MCP를 AI 도구에 연결하는 방법

한국투자증권 Open API를 활용하는 KIS Trade MCP와 KIS Code Assistant MCP를 AI 도구(Claude Desktop | Cursor)에 연결하는 설정 방법을 단계별로 안내합니다.

---

공통사항

한국투자증권 계좌와 한국투자증권 OpenAPI 홈페이지에서 인증정보(App Key, App Secret)를 준비해 주세요.

개발 환경 : Python 3.13 이상 권장

Claude Desktop 또는 Cursor와 같은 한국투자증권 MCP를 연결할 AI 도구를 설치해 주세요.

KIS Open API 신청 및 설정

1. 한국투자증권 계좌 개설 및 ID 연결
2. 한국투자증권 홈페이지 or 앱에서 Open API 서비스 신청
3. 앱키(App Key), 앱시크릿(App Secret) 발급
4. 모의투자 및 실전투자 앱키 각각 준비

🍀 서비스 신청 안내 바로가기

🔗 MCP(Model Context Protocol)란?

MCP는 Claude를 개발한 Anthropic에서 만든 프로토콜로, AI 모델이 외부 도구와 데이터에 안전하고 효율적으로 접근할 수 있게 해주는 표준화된 인터페이스입니다. 이제 한국투자증권이 만든 2개의 MCP를 통해 한국투자증권 Open API를 자연어로 쉽게 활용할 수 있습니다.

한국투자증권 MCP 소개

KIS Trade MCP

특징 및 용도

국내/해외주식, 선물·옵션, 채권, ETF/ETN, 인증 등 한국투자증권의 다양한 Open API를 **MCP 서버의 "도구"**로 래핑하였습니다. LLM이 바로 사용할 수 있도록 API 스키마·파라미터를 리소스로 제공하고, 모의/실전 환경을 구분하여 안전하게 실행합니다.

설정 방법

(9월 중 공개 예정)

KIS Code Assistant MCP

특징 및 용도

한국투자증권의 많은 Open API 중에서 자연어 검색으로 관련 API를 찾고, 호출 예제(파라미터 포함)까지 자동 구성해주는 MCP 서버입니다. "무엇을 하고 싶은지"만 말하면, 관련 API를 추천하고 예시 호출 코드를 만들어 드립니다.

설정 방법

1. Claude Desktop

   Link : https://smithery.ai/server/@KISOpenAPI/kis-code-assistant-mcp

   

   AUTO / Claude Desktop 선택 → Terminal 명령어 Copy 클릭

   

   터미널에 명령어 붙여넣기하고 엔터 → 설치 완료 메시지 후 Claude 재시작 질문에는 Y 입력 후 엔터를 누르면 Claude Desktop 재시작

   

   홈 화면 대화창 하단 검색 및 도구 버튼에서 설치 및 추가 확인 가능, 설정 → 개발자에서도 확인 할 수 있습니다.

2. Cursor

   Link : https://smithery.ai/server/@KISOpenAPI/kis-code-assistant-mcp

   

   AUTO / Cursor 선택 → One-Click Install 클릭

   

   Cursor에서 Install 클릭하면 완료

   

   KIS Code Assistant MCP가 연결되었는지 확인 (경로 : Settings > MCP Servers)

🚀 MCP기반 트레이딩 시스템 개발을 위한 환경 설정

트레이딩 시스템 개발을 시작하기 전에 필요한 Python 환경 구성부터 API 연결 테스트까지 개발 환경 설정 과정을 안내합니다.

1. 폴더 생성 및 파일 다운로드

트레이딩 시스템 개발을 위해 필요한 파일을 다운로드하고 폴더를 생성하고 경로를 지정하세요.

1-1. 보안 폴더 생성

중요 정보를 저장하는 폴더와 실행 코드를 저장하는 폴더를 각각 생성합니다.

맥/리눅스:

mkdir -p ~/KIS/config
cd ~/KIS/config

윈도우 PowerShell:

mkdir "$HOME\KIS\config"
cd "$HOME\KIS\config"

1-2. 프로젝트 폴더 생성

맥/리눅스:

mkdir -p ~/자동매매
cd ~/자동매매

윈도우 PowerShell:

mkdir "$HOME\자동매매"
cd "$HOME\자동매매"

1-3. GitHub에서 파일 다운로드

한국투자증권 GitHub에서 세개 파일을 다운로드 받으세요.

GitHub 링크: https://github.com/koreainvestment/open-trading-api

1. kis_devlp.yaml → ~/kis/config 폴더에 저장 (보안 정보로 별도 관리)

   https://github.com/koreainvestment/open-trading-api/blob/main/kis_devlp.yaml

2. kis_auth.py → ~/자동매매/ 폴더에 저장

   https://github.com/koreainvestment/open-trading-api/blob/main/examples_llm/kis_auth.py

3. pyproject.toml → ~/자동매매/ 폴더에 저장

   https://github.com/koreainvestment/open-trading-api/blob/main/pyproject.toml

경로 표기 안내 문서에서 ~는 **내 사용자 폴더(홈)**를 뜻합니다. ~/{폴더명}은 그 안의 {폴더명} 폴더라는 의미이며, 실제 입력은 ~/kis/config처럼 중괄호 없이 적습니다. (Windows PowerShell: ~ → C:\Users\내이름)

1-4. 중요kis_devlp.yaml 설정

~/KIS/kis_devlp.yaml 파일에 발급받은 App key, App Secret, 계좌정보 (실전, 모의)를 입력하세요

#홈페이지에서 API서비스 신청시 발급 AppKey, AppSecret 값 설정
#실전투자
my_app: "발급받은_실제_APP_KEY"      # 한국투자증권에서 발급받은 APP KEY 입력
my_sec: "발급받은_실제_APP_SECRET"   # 한국투자증권에서 발급받은 APP SECRET 입력

#모의투자  
paper_app: "발급받은_실제_APP_KEY"      # 모의투자용 APP KEY (실전과 동일)
paper_sec: "발급받은_실제_APP_SECRET"   # 모의투자용 APP SECRET (실전과 동일)

# HTS ID
my_htsid: "실제_HTS_ID"              # 한국투자증권 HTS ID 입력

#계좌번호 및 8자리
my_acct_stock: "실제_계좌번호"        # 주식 계좌번호 (예: 50068418)  
my_acct_future: "실제_계좌번호"       # 선물옵션 계좌번호 (주식과 동일 가능)
my_paper_stock: "모의투자_계좌번호"    # 모의투자 주식 계좌번호
my_paper_future: "모의투자_계좌번호"   # 모의투자 선물옵션 계좌번호 (주식과 동일 가능)

#계좌번호 뒤 2자리
my_prod: "01"   # 01(종합계좌), 03(국내선물옵션), 08(해외선물옵션), 22(개인연금), 29(퇴직연금)

⚠️ 보안 주의사항:

• App Key/App Secret과 계좌번호는 절대 타인과 공유하지 마세요.
• GitHub 공개 저장소와 같이 외부에 공개된 저장소에는 절대 업로드하지 마세요.
• 트레이딩 시스템 폴더와 별도의 경로(~/KIS/config)에 보관하세요.
• 정기적으로 API Key를 재발급하여 보안을 강화하세요

2. uv 설치 및 가상환경 설정

2-1. uv 설치

맥/리눅스:

curl -LsSf https://astral.sh/uv/install.sh | sh

윈도우:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2-2. 가상환경 설정

프로젝트 폴더로 이동 후 가상환경 생성:

cd ~/자동매매
uv sync

2-3. 가상환경 활성화

맥/리눅스:

source .venv/bin/activate

윈도우:

.venv\Scripts\activate

3. 연결 테스트 (필수 검증)

3-1. 기본 연결 테스트

~/자동매매/test_connection.py 파일을 생성하고 해당 코드를 복사/붙여넣기 합니다.

(모의투자로 세팅되어 있습니다.)

# test_connection.py
# KIS Open API 연결 테스트 및 기본 정보 확인 스크립트
import sys
import os

try:
    from kis_auth import auth, getTREnv, getEnv, read_token
    import kis_auth
    
    # 설정 파일 확인
    print("설정 파일 확인 중...")
    cfg = getEnv()
    print(f"앱키: {cfg.get('my_app', 'None')[:10]}...")
    print(f"서버 URL: {cfg.get('prod', 'None')}")
    
    # 인증 토큰 발급 테스트
    print("토큰 발급 시도 중...")
    try:
        # 디버그 모드 활성화
        kis_auth._DEBUG = True
        
        auth(svr="vps")  # 모의투자 토큰 발급 및 저장
        print("토큰 발급 완료")
        
        # 토큰이 제대로 설정되지 않은 경우 수동으로 설정
        env = getTREnv()
        if not env.my_token:
            print("토큰이 환경에 설정되지 않음. 저장된 토큰을 확인합니다...")
            saved_token = read_token()
            if saved_token:
                print("저장된 토큰을 찾았습니다. 환경에 설정합니다...")
                # 토큰을 직접 설정
                kis_auth._TRENV = kis_auth._TRENV._replace(my_token=saved_token)
                kis_auth._base_headers["authorization"] = f"Bearer {saved_token}"
                print("토큰 설정 완료")
            else:
                print("저장된 토큰도 없습니다.")
        
    except Exception as auth_error:
        print(f"토큰 발급 중 오류: {auth_error}")
        import traceback
        traceback.print_exc()
    
    # 환경 정보 확인
    env = getTREnv()
    
    if hasattr(env, 'my_token') and env.my_token:
        print("✅ API 연결 성공!")
        print(f"토큰 앞 10자리: {env.my_token[:10]}...")
        print(f"계좌번호: {env.my_acct}")
        print(f"서버: {'모의투자' if env.my_url.find('vts') > 0 else '실전투자'}")
    else:
        print("❌ API 연결 실패 - 토큰이 없습니다")
        print(f"토큰 속성 존재: {hasattr(env, 'my_token')}")
        if hasattr(env, 'my_token'):
            print(f"토큰 값: {env.my_token}")
            print(f"토큰 길이: {len(env.my_token) if env.my_token else 0}")

except Exception as e:
    print(f"❌ 오류 발생: {e}")
    print("devlp.yaml 파일 경로와 설정을 확인해주세요")

3-2. 테스트 실행

테스트를 실행하고 결과를 확인하세요.

# 실행
cd ~/자동매매
python test_connection.py

# 결과
✅ API 연결 성공!
토큰 앞 10자리: asdfasdfas...
계좌번호: 12345678
서버: 모의투자

🛠️ 자주 발생하는 문제와 해결방법

1. MCP 연결 실패 시
   • Claude Desktop/Cursor 재시작
   • MCP 서버 URL 확인 (https://smithery.ai/server/@KISOpenAPI/kis-code-assistant-mcp)
   • 방화벽 설정 확인
   • 인터넷 연결 확인
2. API 연결 오류 시
   • App Key와 Secret이 발급 받은 것과 동일한지 확인
   • kis_auth.py 의 내용이 다운로드 받은 파일과 동일한지 확인
   • kis_devlp.yaml 파일이 “~/KIS/config/” 혹은 “$HOME/KIS/config”에 있는지 확인
   • kis_devlp.yaml 파일에 작성한 개인정보가 정확한지 확인 (App Key/Secret, HTS ID, 계좌번호, 상품코드)
   • kis_devlp.yaml 파일의 문법이 올바른지 확인 (YAML 문법, 들여쓰기 주의)
3. 가상환경 문제 시
   • uv 버전 확인: uv --version
   • pyproject.toml 의 내용이 다운로드 받은 파일과 동일한지 확인
   • 프로그램 실행에 필요한 전체 패키지 재설치: uv sync
   • 가상환경 재생성: uv venv --force
4. Python 모듈 import 오류 시
   • 가상환경 활성화 확인
   • 필요 패키지 설치: uv add {패키지명}

---

4. 최종 폴더 구조 확인

설정이 성공적으로 완료되면 폴더 구조는 다음과 같습니다.

~/KIS/
└── config/
    └── devlp.yaml (보안 정보)

~/자동매매/
├── kis_auth.py
├── pyproject.toml
├── test_connection.py
├── .venv/ (uv sync 후 자동 생성)
└── uv.lock (uv sync 후 자동 생성)

---

Next Step

설정이 완료되셨다면 이제 투자를 위한 전략를 구현하세요.

1. 🎯 MCP를 활용하여 개발 시작하기
   • Cursor에서 KIS Code Assistant MCP를 활용하여 자동매매 시스템 개발
   • 자연어로 '주식 현재가 조회 코드 보여줘' 같은 질문하기
2. 📊 모의투자 환경에서 충분한 테스트 진행
   • 실제 거래 전 반드시 모의투자로 검증
   • 손절/익절 로직 구현 및 테스트
3. 🔒 실전 투자 적용 시 보안과 리스크 관리 강화
   • 포트폴리오 분산 투자 권장
   • 정기적인 API 키 교체

🚀 고급 활용 팁

• 백테스팅을 통한 전략 검증
• 실시간 알림 시스템 구축
• 리스크 관리 자동화

---

한국투자증권은 기술을 통해 투자의 진입장벽을 낮추고, 투자자들이 더 나은 투자 경험을 할 수 있도록 MCP를 통해 복잡한 API 연동 등 개발환경을 개선하여 투자 전략 본질에 집중할 수 있도록 지원합니다.

AI와 함께하는 새로운 투자 시대, 여러분만의 성공 투자 스토리에 한국투자증권 MCP가 든든한 파트너가 되겠습니다.