# 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. **모의투자** 및 **실전투자** 앱키 각각 준비 🍀 [서비스 신청 안내 바로가기](https://apiportal.koreainvestment.com/about-howto) # 🔗 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](https://smithery.ai/server/@KISOpenAPI/kis-code-assistant-mcp) image image 1 **AUTO / Claude Desktop** 선택 → Terminal 명령어 Copy 클릭 image 2 터미널에 명령어 붙여넣기하고 엔터 → 설치 완료 메시지 후 Claude 재시작 질문에는 Y 입력 후 엔터를 누르면 Claude Desktop 재시작 image 3 홈 화면 대화창 하단 **검색 및 도구** 버튼에서 설치 및 추가 확인 가능, `설정 → 개발자`에서도 확인 할 수 있습니다. 2. Cursor Link : [https://smithery.ai/server/@KISOpenAPI/kis-code-assistant-mcp](https://smithery.ai/server/@KISOpenAPI/kis-code-assistant-mcp) image 4 image 5 **AUTO / Cursor** 선택 → **One-Click Install** 클릭 image 6 Cursor에서 **Install** 클릭하면 완료 image 7 KIS Code Assistant MCP가 연결되었는지 확인 (경로 : `Settings` > `MCP Servers`) # 🚀 MCP기반 트레이딩 시스템 개발을 위한 환경 설정 트레이딩 시스템 개발을 시작하기 전에 필요한 Python 환경 구성부터 API 연결 테스트까지 개발 환경 설정 과정을 안내합니다. ### 1. 폴더 생성 및 파일 다운로드 트레이딩 시스템 개발을 위해 필요한 파일을 다운로드하고 폴더를 생성하고 경로를 지정하세요. ### **1-1. 보안 폴더 생성** 중요 정보를 저장하는 폴더와 실행 코드를 저장하는 폴더를 각각 생성합니다. **맥/리눅스**: ```bash mkdir -p ~/KIS/config cd ~/KIS/config ``` **윈도우 PowerShell**: ```powershell mkdir "$HOME\KIS\config" cd "$HOME\KIS\config" ``` ### **1-2. 프로젝트 폴더 생성** **맥/리눅스**: ```bash mkdir -p ~/자동매매 cd ~/자동매매 ``` **윈도우 PowerShell**: ```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, 계좌정보 (실전, 모의)를 입력하세요 ```yaml #홈페이지에서 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 설치** **맥/리눅스**: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` **윈도우**: ```powershell powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` ### **2-2. 가상환경 설정** 프로젝트 폴더로 이동 후 가상환경 생성: ```bash cd ~/자동매매 uv sync ``` ### **2-3. 가상환경 활성화** **맥/리눅스**: ```bash source .venv/bin/activate ``` **윈도우**: ```bash .venv\Scripts\activate ``` ## 3. 연결 테스트 (필수 검증) ### 3-1. 기본 연결 테스트 `~/자동매매/test_connection.py` 파일을 생성하고 해당 코드를 복사/붙여넣기 합니다. (모의투자로 세팅되어 있습니다.) ```python # 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. 테스트 실행 테스트를 실행하고 결과를 확인하세요. ```bash # 실행 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](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가 든든한 파트너가 되겠습니다.