Claude Desktop으로 자동매매 코드 오류 잡기 —AI가 내 파이썬 파일을 직접 읽는다

직장인 자동매매 시리즈 · 6편

Claude Desktop으로 자동매매 코드 오류 잡기 —
AI가 내 파이썬 파일을 직접 읽는다

2026년 5월 파이썬 설치 · KIS API · Claude Desktop 코드 스니펫 4개

← 5편 읽기: ETF 적립식 투자와 주식 자동매매 병행하는 법 — 직장인 자금 배분 전략

자동매매를 시작하고 싶은데 가장 먼저 막히는 곳이 있어요. 전략도 아니고 코드도 아닌, 환경 세팅입니다. 파이썬 설치부터 막히고, 설치가 됐는데 API 호출이 안 되고, 코드는 돌아가는데 오류가 나서 뭘 고쳐야 할지 모르는 그 시간.

저도 처음엔 그랬어요. 컴퓨터를 잘 다루는 편도 아니었고, "터미널"이라는 단어조차 낯설었습니다. 검은 화면에 글자만 깜빡이는 cmd 창을 처음 열었을 때 뭘 입력해야 할지 몰라서 그냥 닫아버린 적도 있어요. 그런데 지금은 달라요. Claude Desktop이 생기고 나서부터요. 터미널 오류 메시지를 그대로 복사해서 붙여넣으면 원인과 수정 코드를 바로 받을 수 있어요. 내 파이썬 파일을 직접 읽고 "이 함수 여기가 문제예요"라고 집어줍니다.

이 글은 세 파트로 구성돼 있어요. 파이썬 설치 → KIS API 연동 → Claude Desktop 연동. 순서대로 하나씩 따라오시면 됩니다. 중간에 막혀도 괜찮아요. 어디서 막히는지, 어떤 화면이 보여야 정상인지, 자주 나는 오류는 뭔지까지 함께 적어뒀어요. 이 글 하나로 자동매매 개발 환경을 처음부터 끝까지 완성할 수 있습니다.

⏱️

예상 소요 시간 약 1시간. 컴퓨터 다루는 게 서툴러도 괜찮아요. 천천히, 순서대로만 따라오시면 됩니다.

PART A — 파이썬 설치

python.org 다운로드부터 첫 실행 확인까지

파이썬 설치 — 딱 3단계, 함정 2개

PART A

파이썬은 자동매매 코드를 실행해주는 "엔진"이에요. 엔진이 없으면 아무리 좋은 설계도가 있어도 차가 움직이지 않는 것처럼, 파이썬이 없으면 코드를 짜놔도 실행이 안 됩니다. 설치는 어렵지 않아요. 딱 세 단계인데, 그 중 한 단계에서 거의 모든 초보자가 똑같이 막히는 부분이 있어서 그것만 짚어드릴게요.

1

python.org/downloads 접속 → 최신 버전 다운로드

검색창에 "python download"라고 치면 가장 위에 공식 사이트가 나와요. 들어가면 노란색 "Download Python 3.x.x" 버튼이 큼지막하게 보입니다. 그냥 그 버튼을 누르면 돼요. 버전은 3.8 이상이면 어떤 것이든 상관없어요. 나오는 숫자가 3.10이든 3.12든 3.13이든 신경 쓰지 않아도 됩니다.

🖥️ 이런 화면이 보여야 정상이에요

python.org → "Download Python 3.13.x" (노란색 버튼) → 클릭하면 .exe 파일 다운로드 시작

2

다운로드된 파일 실행 → "Add Python to PATH" 반드시 체크

다운로드 폴더에서 방금 받은 파일(보통 python-3.13.x-amd64.exe 같은 이름)을 더블클릭해서 실행하세요. 설치 화면이 뜨면 맨 아래쪽에 작은 체크박스가 있어요. "Add Python.exe to PATH" 또는 "Add python.exe to PATH"라고 쓰여 있습니다. 이 글에서 가장 중요한 한 줄이 바로 이거예요. 반드시 체크하고 "Install Now"를 누르세요.

🖥️ 설치 화면에서 확인할 것

☐ Add python.exe to PATH ← 이 체크박스를 ✅로 바꾸기
[Install Now] 버튼 클릭

3

설치 완료 후 확인 — cmd 열고 두 줄 입력

설치가 끝나면 잘 됐는지 확인해야 해요. 윈도우 키를 누르고 "cmd"라고 입력하면 "명령 프롬프트"라는 검은 화면 프로그램이 검색돼요. 그걸 클릭해서 여세요. 검은 화면에 깜빡이는 줄(커서)이 보이면 정상입니다. 아래 두 줄을 그대로 입력하고 엔터를 누르세요.

# 설치 확인 (cmd에서 입력 후 엔터) python --version # Python 3.13.x 처럼 나오면 성공 pip --version # pip 25.x.x 처럼 나오면 성공

🖥️ 이렇게 나오면 성공이에요

C:\Users\사용자명> python --version
Python 3.13.2

C:\Users\사용자명> pip --version
pip 25.0.1 from C:\...\Lib\site-packages\pip (python 3.13)

버전 숫자가 나오면 끝났어요. 다음 단계로 넘어가세요. 혹시 숫자가 안 나오고 빨간 글씨로 뭔가 떴다면, 아래 함정 두 개를 확인해보세요.

⚠️ 초보자 함정 ①: "'python'은 내부 또는 외부 명령... 이 아닙니다" 오류

Step 2에서 PATH 체크박스를 안 누른 경우 정확히 이 오류가 나요. 당황하지 마세요. 파이썬을 제거하고 다시 설치하면 해결됩니다. "앱 및 기능"에서 Python을 찾아 제거한 다음, Step 1로 돌아가서 다시 설치하고, 이번엔 체크박스를 꼭 누르세요. 이 작은 체크박스 하나가 전체 과정에서 가장 많이 놓치는 부분이에요.

⚠️ 초보자 함정 ②: pip 업데이트 알림이 오류인 줄 알았어요

버전 확인할 때 [notice] A new release of pip is available처럼 회색 글씨로 뭔가 뜨는 경우가 있어요. 이건 오류가 아니라 "pip 새 버전 나왔어요" 알림일 뿐이에요. 스마트폰 앱 업데이트 알림 같은 거예요. 무시하고 그냥 다음 단계로 넘어가시면 됩니다. 빨간 글씨로 "Error"가 떠야 진짜 오류예요.

패키지 설치 — 자동매매에 필요한 도구 챙기기

파이썬 설치가 됐으면 자동매매에 필요한 패키지(도구 모음)를 설치할게요. 방금 열었던 cmd 창에 아래 한 줄을 그대로 입력하고 엔터를 누르세요.

# 필요한 패키지 설치 (cmd에서 입력) pip install requests pandas python-dotenv

화면에 글자들이 쭉쭉 올라가면서 설치가 진행돼요. 몇 초에서 몇 분 정도 걸릴 수 있어요. 인터넷 속도에 따라 다릅니다. 마지막에 Successfully installed ...라는 줄이 보이면 끝났어요.

프로젝트 폴더와 .env 파일 만들기

이제 작업할 폴더를 하나 만들어야 해요. 바탕화면에서 마우스 오른쪽 버튼을 클릭 → 새로 만들기 → 폴더를 선택하고, 이름을 trading이라고 지으세요. 앞으로 이 폴더 안에 모든 코드와 설정 파일을 모아둘 거예요.

.env 파일 — API 키를 안전하게 보관하는 방법

trading 폴더 안에서 마우스 오른쪽 → 새로 만들기 → 텍스트 문서를 선택하세요. 파일이 생기면 이름을 .env.txt가 아니라 정확히 .env로 바꿔야 해요. 이름을 바꿀 때 "이름을 바꾸면 사용할 수 없게 될 수도 있습니다"라는 경고가 떠도 "예"를 눌러서 진행하면 됩니다. 만약 확장자(.txt)가 안 보인다면, 파일 탐색기 상단의 "보기" 메뉴 → "파일 확장명" 체크박스를 켜면 보여요. 이 단계에서 헷갈려서 .env.txt로 저장하는 경우가 정말 많은데, 이렇게 되면 나중에 코드가 키를 못 읽어요. 꼭 확인하세요.

PART B — KIS API 연동

APP_KEY 발급 → 토큰 발급 → 첫 호출 성공

KIS API 연동 — 신청부터 첫 호출까지

PART B

이제 한국투자증권에서 제공하는 API(자동매매를 위한 통신 창구)를 연결할 거예요. API는 "내 컴퓨터 프로그램이 증권사 서버에 말을 거는 통로"라고 생각하면 됩니다. 이 통로를 열려면 "신청 → 키 발급 → 인증" 세 단계가 필요해요.

1단계 — 신청하기

apiportal.koreainvestment.com에 접속해서 한국투자증권 계정으로 로그인하세요. 계좌가 없다면 한국투자증권 앱에서 비대면으로 먼저 만들어야 해요. 로그인 후 "KIS Developers 서비스 신청"을 찾아서 누르고, 화면에 나오는 안내를 따라가면 됩니다. 여기서 중요한 건 실전 계좌와 모의 계좌를 각각 따로 신청해야 한다는 점이에요. 두 계좌가 서로 다른 키를 갖게 됩니다.

2단계 — APP_KEY / APP_SECRET 받기

신청이 끝나면 같은 사이트 대시보드에서 APP_KEY와 APP_SECRET이라는 긴 문자열 두 개가 발급돼요. 이게 내 프로그램이 증권사 서버에 "저는 인증된 사용자예요"라고 증명하는 신분증 같은 역할을 합니다. 복사 버튼을 눌러서 어딘가에 잠깐 메모해두세요. 곧 쓸 거예요.

이제 이 두 키를 아까 만든 .env 파일에 저장할 거예요. 메모장으로 .env 파일을 열고 아래 내용을 붙여넣은 다음, 여기에_..._붙여넣기 부분만 실제로 발급받은 값으로 바꿔서 저장하세요.

# .env 파일 내용 — 메모장으로 열어서 붙여넣기 KIS_APP_KEY=여기에_실전_APP_KEY_붙여넣기 KIS_APP_SECRET=여기에_실전_APP_SECRET_붙여넣기 KIS_CANO=계좌번호_앞8자리 KIS_ACNT_PRDT=01 # 모의 계좌 (이름을 다르게 저장) KIS_APP_KEY_DEMO=여기에_모의_APP_KEY_붙여넣기 KIS_APP_SECRET_DEMO=여기에_모의_APP_SECRET_붙여넣기

계좌번호는 어디서 보나요?

한국투자증권 계좌번호는 44289555-01 같은 형태예요. 하이픈 앞 8자리 숫자가 위 코드의 KIS_CANO, 뒤 2자리가 KIS_ACNT_PRDT입니다. 계좌번호는 한국투자증권 앱이나 위 대시보드에서 확인할 수 있어요.

3단계 — 첫 코드 실행해보기

이제 진짜로 작동하는지 테스트할 차례예요. 메모장을 열고 아래 코드를 전체 복사해서 붙여넣은 다음, trading 폴더 안에 test_api.py라는 이름으로 저장하세요. 저장할 때 파일 형식을 "모든 파일"로 바꿔야 .py 확장자가 제대로 붙어요.

# test_api.py — 토큰 발급 + 삼성전자 현재가 조회 import os, requests from dotenv import load_dotenv load_dotenv() # .env 파일을 자동으로 읽어옴 APP_KEY = os.environ.get("KIS_APP_KEY") APP_SECRET = os.environ.get("KIS_APP_SECRET") BASE_URL = "https://openapi.koreainvestment.com:9443" # 1. 토큰 발급 — 신분증 같은 인증키를 받는 단계 res = requests.post(BASE_URL + "/oauth2/tokenP", json={ "grant_type": "client_credentials", "appkey": APP_KEY, "appsecret": APP_SECRET, }) token = res.json()["access_token"] print(f"✅ 토큰 발급 성공: {token[:20]}...") # 2. 삼성전자 현재가 조회 — 진짜로 연결됐는지 확인 headers = { "authorization": f"Bearer {token}", "appkey": APP_KEY, "appsecret": APP_SECRET, "tr_id": "FHKST01010100", } r = requests.get(BASE_URL + "/uapi/domestic-stock/v1/quotations/inquire-price", headers=headers, params={"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": "005930"}) price = r.json()["output"]["stck_prpr"] print(f"삼성전자 현재가: {int(price):,}원")

저장이 끝났으면 cmd 창으로 돌아가서 다음을 입력하세요. trading 폴더로 먼저 이동해야 해요.

# cmd에서 trading 폴더로 이동 후 실행 cd Desktop\trading python test_api.py

🖥️ 이렇게 나오면 성공이에요

✅ 토큰 발급 성공: eyJ0eXAiOiJKV1QiLCJh...
삼성전자 현재가: 78,500원

화면에 토큰 발급 성공 메시지와 실제 주가 숫자가 보이면 이제 내 컴퓨터가 한국투자증권 서버와 정상적으로 통신하고 있다는 뜻이에요. 여기까지 왔으면 정말 큰 산을 넘은 거예요.

⚠️ BASE_URL 주의 — openapivts가 아닙니다

구글에서 옛날 글을 찾아보면 BASE_URL이 openapivts.koreainvestment.com으로 된 경우가 있어요. 이건 예전 구조예요. 지금은 실전과 모의 모두 openapi.koreainvestment.com:9443 하나로 통일됐고, tr_id(요청 종류를 나타내는 코드) 앞글자로 환경을 구분합니다. TTTC로 시작하면 실전, VTTC로 시작하면 모의예요.

자주 나오는 오류와 해결책

여기까지 오는 동안 막힐 수 있는 대표적인 오류 세 가지를 정리했어요.

① 토큰 발급 실패 — 401 Unauthorized

화면에 401이라는 숫자가 보이는 오류예요. 대부분 APP_KEY나 APP_SECRET을 복사할 때 앞이나 뒤에 빈 칸이 같이 복사된 경우입니다.

✓ 해결: .env 파일을 다시 열어서 키 값 앞뒤에 공백이 없는지 눈으로 확인하세요. 줄 끝에 스페이스바가 눌려있을 수도 있어요.

② 잔고 현금이 0원으로 나옴

계좌에 분명 돈이 있는데 코드로 조회하면 0원이라고 나오는 경우예요. 증권사 API 응답에서 현금을 나타내는 항목 이름이 바뀌어서 생기는 문제입니다.

✓ 해결: 코드에서 dnca_tot_amt 대신 prvs_rcdl_excc_amt라는 항목 이름을 사용하면 정상적으로 나와요.

③ 거래대금 필터가 아무것도 안 걸러냄

"거래대금 1,000억 이상인 종목만 보겠다"는 필터를 만들었는데 전부 통과하거나 전부 걸러지는 경우예요. 거래대금 숫자가 원 단위로 올 때도 있고 만원 단위로 올 때도 있어서 생기는 문제입니다.

✓ 해결: 받아온 숫자가 1조(1,000,000,000,000) 미만이면 만원 단위라고 판단하고 10,000을 곱해서 원 단위로 바꿔주세요.

PART C — Claude Desktop 연동

이 편의 핵심 — AI가 내 폴더를 직접 읽는다

Claude Desktop이란 — 코딩 몰라도 되는 이유

PART C

여기까지 따라오면서 빨간 오류 글씨를 몇 번이나 보셨을 거예요. 예전엔 이런 오류가 나면 그 메시지를 그대로 구글에 검색하고, 영어로 된 스택오버플로우 글을 번역기로 돌려보고, 몇 시간씩 헤맸어요. 지금은 그럴 필요가 없습니다.

Claude Desktop은 내 컴퓨터의 폴더와 파일에 직접 접근할 수 있는 AI 프로그램이에요. 웹브라우저에서 쓰는 Claude와 다른 점이 바로 이거예요. 웹에서는 코드를 일일이 복사해서 붙여넣어야 하지만, Claude Desktop은 trading 폴더를 한 번 연결해두면 "이 폴더에 있는 test_api.py 파일을 읽고 오류 원인을 알려줘"라고 말만 하면 실제로 그 파일을 열어서 읽고 답해줍니다.

코드를 못 짜도 괜찮다. Claude Desktop이 짜준다. 내가 할 일은 오류 메시지를 복사하는 것뿐이다.

Claude Desktop 설치 + trading 폴더 연결

1

claude.ai/download 접속 → 설치 → 로그인

브라우저에서 claude.ai/download에 들어가면 운영체제에 맞는 다운로드 버튼이 보여요. Windows를 쓰면 Windows 버튼, Mac을 쓰면 Mac 버튼을 누르면 됩니다. (macOS 11 이상, Windows 10 이상이면 설치 가능해요.) 다운로드된 파일을 실행해서 설치를 마치고, 평소 쓰던 Claude 계정으로 로그인하면 끝입니다.

2

설정 → 개발자 → "구성 편집" 클릭

Claude Desktop을 열면 화면 어딘가에 설정(톱니바퀴 아이콘)이 있어요. 그걸 누르고 들어가면 왼쪽에 메뉴 목록이 보이는데, 그 중 "개발자"를 클릭하세요. "구성 편집"이라는 버튼이 보이면 클릭합니다. 그러면 메모장 같은 프로그램이 자동으로 열리면서 claude_desktop_config.json이라는 파일이 나타나요. 이 파일이 Claude Desktop에게 "어떤 폴더를 볼 수 있게 해줄지" 알려주는 설정표입니다.

3

파일 내용을 전부 지우고 아래 내용으로 교체

열린 파일 안에 원래 있던 내용을 전체 선택(Ctrl+A)해서 지우고, 아래 코드를 그대로 복사해서 붙여넣으세요. "사용자명" 부분만 내 컴퓨터의 실제 사용자 이름으로 바꿔야 해요. 사용자 이름은 보통 바탕화면 경로(C:\Users\사용자명\Desktop)에서 확인할 수 있어요.

// claude_desktop_config.json (Windows 기준) { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\사용자명\\Desktop\\trading" ] } } } // Mac을 쓰는 경우 경로 부분만 이렇게 바꾸세요 // "/Users/사용자명/Desktop/trading"

붙여넣은 다음 Ctrl+S로 저장하고 파일을 닫으세요.

4

Claude Desktop 완전히 끄고 다시 켜기

그냥 창을 닫는 것만으로는 부족해요. Windows라면 화면 오른쪽 아래 트레이 아이콘에서 Claude를 찾아 완전히 종료하고, 다시 실행해야 설정이 적용됩니다. 다시 켜고 새 대화창을 열면 왼쪽 아래쯔음에 작은 플러그 모양 아이콘(🔌)이 보여야 해요. 그 아이콘이 보이면 trading 폴더 연결이 성공한 거예요.

⚠️ JSON 쉼표 오류 — 가장 흔한 실수

설정 파일을 손으로 고치다 보면 쉼표 하나 때문에 전체가 안 열리는 경우가 많아요. 예를 들어 마지막 항목 뒤에 쉼표(,)가 남아있으면 오류가 나요. 가장 안전한 방법은 위 코드 블록을 통째로 복사해서 그대로 붙여넣고, 사용자명 부분만 바꾸는 거예요. 직접 타이핑하다가 괄호나 쉼표를 놓치는 경우가 흔합니다. Claude Desktop을 재시작했는데 플러그 아이콘이 안 보인다면 이 부분을 가장 먼저 확인해보세요.

이렇게 물어보면 됩니다 — 실전 프롬프트 5가지

연결이 끝났으면 이제 실제로 어떻게 활용하는지가 중요해요. 아래 다섯 가지는 자동매매 코드를 다룰 때 가장 자주 쓰는 질문 패턴이에요. 그대로 따라 써보면서 감을 잡으시면 됩니다.

오류 디버깅

"터미널에서 이런 오류가 났어. trading 폴더의 kis_auth_wrapper.py를 읽고 원인과 수정 방법을 알려줘. [오류 메시지 붙여넣기]"

코드 이해

"trading 폴더의 turtle_live_trader.py를 읽고 감시 종목이 어떻게 선정되는지 초보자도 이해할 수 있게 설명해줘"

로그 분석

"trading/logs 폴더에서 오늘 날짜 로그 파일을 읽고 손절이 몇 번 발생했는지, 원인이 뭔지 알려줘"

파라미터 질문

"KIS API에서 tr_id TTTC0012U랑 VTTC0012U 차이가 뭐야? 실전이랑 모의 언제 어떻게 바꾸는 거야?"

코드 수정

"trading 폴더의 kis_auth_wrapper.py를 읽고 현금잔고 조회가 항상 0으로 나오는 문제를 수정해줘"

Claude Desktop이 없어도 괜찮아요

설치가 너무 복잡하게 느껴진다면 일단 넘어가도 괜찮아요. 웹브라우저에서 쓰는 Claude(claude.ai)에서도 오류 메시지나 코드를 직접 복사해서 붙여넣으면 똑같이 도움을 받을 수 있어요. Claude Desktop은 "파일을 직접 읽어준다"는 편의성을 더해주는 것이지, 없으면 못 하는 건 아닙니다. 나중에 여유가 생기면 다시 시도해보세요.

세팅 완료 체크리스트

마무리

여기까지 모두 따라오셨다면 아래 네 가지가 전부 확인됐을 거예요.

✓

파이썬 설치 확인

python --version 입력 시 버전 번호가 화면에 나온다

✓

KIS API 토큰 발급 성공

"✅ 토큰 발급 성공" 메시지가 화면에 출력된다

✓

삼성전자 현재가 조회 성공

실제 주가와 비슷한 숫자가 화면에 출력된다

✓

Claude Desktop 연동 성공

새 대화창에 🔌 아이콘이 보이고 폴더 내 파일을 읽을 수 있다

네 가지가 모두 확인됐다면 자동매매를 위한 개발 환경이 완성된 거예요. 여기서부터는 전략을 코드로 옮기는 재미있는 부분이 시작됩니다.

세팅에서 막히는 건 실력 문제가 아니다. 문서가 처음 보는 사람에게 친절하지 않은 것뿐이다. 막히면 Claude Desktop에 그대로 물어보면 된다.

이 글에서 다루지 못한 웹소켓 실시간 시세 연동이나 고급 API 기능은 apiportal.koreainvestment.com 공식 문서를 참고하세요. 세팅 중 막히는 부분이 있다면 댓글로 남겨주세요. 어느 단계에서 어떤 오류가 났는지 적어주시면 함께 해결해드릴게요.