kis-trading-mcp

name

kis-trading-mcp

description

한투 공식 도구 둘(코딩도우미 334 · 트레이딩 166)을 구분하고, Docker 로 트레이딩 MCP 를 붙인 뒤 조회·액션을 둘러보고 쓸 것을 고른다. Docker 설치·실행·연결은 **AI가 대신** 한다 — 학생은 설치 창을 누르고 앱을 한 번 켠다. Docker 앱이 2분 안에 준비되지 않으면 멈추고 kis-lecture-lab 으로 간다. 수업은 그래도 된다. "트레이딩 MCP", "공식 MCP", "코딩도우미 MCP", "도커", "도커 설치", "조회와 액션", "카탈로그", "334", "166", "kis-trade-mcp", "공식 도구 붙여", "엔드포인트 둘러봐" 라고 하면 반드시 이 스킬. 경계 — "숙제"만 말하면 homework 다. 이 스킬은 homework 가 1주차 1번에서 읽는다. 습관 인터뷰와 모의주문은 investment-habit-rules 가 이어받는다. 토요일 수업 연결은 kis-lecture-lab. 자료 맞춤은 environment. 에러는 troubleshooting.

공식 도구 — 코딩도우미(보기) · 트레이딩(호출)

대상은 비개발자다. 한 번에 한 단계. 쉬운 말. 시작 전에 references/split.md 를 읽는다. 숫자를 섞지 마라.

• 👀 코딩도우미 = 문서 334. 찾기·샘플. 주문 없음.
• 🔧 트레이딩 = 호출 166. 시세·잔고·모의주문. Docker 필요.
• kis-lecture-lab = 수업 다섯. 토요일. 지우지 마라.

주문을 코딩도우미로 넣으면 주문이 안 나간다. 호출·주문은 트레이딩 MCP 만.

Docker 가 안 되면 숙제를 못 하는 게 아니다. kis-lecture-lab 다섯 개로 모의주문·잔고·수익률까지 다 된다. 공식 도구는 더 많은 엔드포인트를 둘러보기 위한 것이다. Docker 앱이 2분 안에 준비되지 않으면 멈추고 랩으로 간다. 낙오가 아니라고 학생에게 말해 준다. KIS_ENV=real 이거나 env_dv=real 이면 멈춘다. 숙제는 모의(demo)만. 키 숫자는 화면에 다시 그리지 마라. .env 에만 넣는다. 한 칸이 끝나면 ../assistant/references/digest.md 의 🧃 한입 을 보여 주고 멈춘다.

설치·패치 세부는 lessons/참고/kis-mcp-연동-가이드.md. 이 스킬이 순서를 정한다. 이 기수는 Windows. python3 없음. python 만.

⚠️ 2026-08-27 · 한국투자증권 보안 업데이트

공식 저장소(open-trading-api)에 보안 개선이 적용되었습니다. 1주차 숙제로 이미 받아 두신 분은 최신으로 다시 받으시기 바랍니다.

open-trading-api 를 최신으로 받아 줘.
1) 1주차에 clone 해 둔 폴더에서 git pull 해 줘.
2) 도커 이미지를 다시 만들어 줘. 컨테이너도 새로 띄워 줘.
3) 잘 붙었는지 조회 한 번으로 확인해 줘.

수업 실습에는 영향이 없습니다. 우리는 그 저장소의 backtester · strategy_builder 를 쓰지 않습니다. 백테스팅은 고정 참조 결과를 읽는 routines/참조전략-실험.py 가 대신합니다. 다만 같은 저장소를 받아 두었으므로 최신으로 맞추는 편이 낫습니다.

공지 원문: https://apiportal.koreainvestment.com/community

카드 (모양을 바꾸지 마라)

시작에 한 장.

🔧 한투 공식 도구 · 둘
────────────────
👀 코딩도우미  = 문서 334개 검색 · 샘플 코드. 주문 없음
🔧 트레이딩    = 호출 166개. 시세·잔고·모의주문. Docker
────────────────
수업 토요일   : kis-lecture-lab (연습 5개). Docker 없음
평일 숙제     : 👀로 둘러보고, 트레이딩 MCP 로만 부른다
실전 계좌     : 숙제 아님
────────────────

이번 실행의 N

평일 장중(9시~15시 반)이 아니면 호출·주문 단계는 하지 말고 둘러보기까지. 키가 없으면 둘러보기까지. 호출은 「키·장 시간이 아니라 여기까지」를 한 줄.

• 키와 장중이면 N = 8. 구분 → 도커 → 트레이딩 붙임 → 코딩도우미 붙임 → 둘러보기 → 고르기 → 조회 → (주문은 습관 스킬).
• 키 없거나 장 시간이 아니면 N = 6. 주문·실조회는 안 한다.

시작 한 줄: 「공식 도구는 둘입니다. 문서는 코딩도우미, 호출·주문은 트레이딩입니다. 트레이딩은 Docker가 필요합니다. 한 번에 하나만 합니다.」

단계

1 · 구분

카드를 보여 준다. "문서 334개를 찾는 손 이름이 뭐예요? 주문이 나가는 손 이름은요?"

정답: 코딩도우미 / 트레이딩(또는 kis-trade-mcp). kis-lecture-lab 만 말하면: 「그건 토요일 다섯 개입니다. 평일 공식 도구는 둘입니다.」 코딩도우미로 주문하겠다고 하면: 「그 손으로는 주문이 안 나갑니다.」

완료: 학생이 둘을 다르게 말했다. 🧃 한입 · 손 둘

2 · Docker — 네가 끝까지 한다

학생은 비개발자다. docker 라는 말을 처음 듣는 사람이 대부분이다. 명령을 알려주지 마라. 네가 실행하고 결과만 말해 준다.

먼저 네가 8초 제한으로 확인한다.

docker --version
docker ps

둘 다 되면 3번으로 간다. 학생에게 아무것도 시키지 않는다.

docker: command not found 면 — 안 깔린 것이다. 이렇게 말한다.

「Docker 라는 걸 하나 깔아야 합니다. 증권사 공식 도구가 그 안에서 돕니다. 받는 건 제가 못 해서 여기만 직접 눌러 주셔야 합니다. 2~3분 걸립니다.」

• 설치 페이지: https://www.docker.com/products/docker-desktop/
• Windows: 설치 중 Use WSL 2 체크. 설치가 끝나면 재부팅을 물어본다 — 하라고 한다.
• 설치 뒤 Docker Desktop 앱을 한 번 실행해야 한다. 깔기만 하고 안 켜면 docker ps 가 안 된다. 이게 제일 흔한 막힘이다. 「고래 모양 아이콘을 한 번 눌러 실행해 주세요」라고 말한다.

docker ps 가 Cannot connect to the Docker daemon 이면 — 깔렸는데 안 켜진 것이다. 학생에게 앱 실행을 부탁하고, 네가 다시 확인한다. 설치 직후 첫 시작만 최대 2분이다. 2분은 Docker의 기술 제한이 아니라 수업에서 무한 대기를 막는 진행 상한이다. 평소 확인은 8초다. 앱 강제 종료·재시작은 한 번만 하고, 그 뒤에도 안 되면 더 기다리지 않는다. 학생에게 "됐나요?" 를 반복해 묻지 마라. 네가 확인한다.

막히는 경우와 그때 할 일:

무엇	어떻게
회사 노트북·관리자 암호	더 밀지 마라. 아래 「Docker 없이」로 간다
Windows Home 이라 안 된다고 나옴	WSL 2 로 된다. 그래도 막히면 「Docker 없이」
2분 넘게 daemon이 안 뜸	멈춘다. 「Docker 없이」

Docker 없이 (막혔을 때) — 숙제를 못 한 게 아니다. kis-lecture-lab 다섯 개로 모의주문·잔고·수익률까지 다 된다. 6번 고르기는 목록 문서로 하고, 내-투자-판단.md 에 「공식 도구 못 붙임 — 이유 한 줄」을 남긴다. 그게 2주차 이야깃거리다. 낙오가 아니라고 분명히 말해 준다.

완료: docker ps 가 되거나, 「Docker 없이」로 넘어갔다. 🧃 한입 · Docker

3 · 트레이딩 MCP 붙임 — 네가 띄운다

lessons/참고/kis-mcp-연동-가이드.md 대로 네가 한다. 학생은 Docker 명령이나 토큰을 직접 조립하지 않는다. ROOT에서 한 명령만 실행한다.

python hermes/setup_kis_mcp.py

스크립트가 공식 저장소·Docker 이미지·모의 키 파일·Bearer 토큰·Hermes 등록을 안전하게 처리한다. 주소는 127.0.0.1, 전송은 transport: sse인 legacy SSE다. Hermes가 URL을 Streamable HTTP로 추측하게 두면 /sse에서 405가 나므로 전송 방식을 반드시 명시한다. 비밀값은 출력하지 않고 기존 .env와 kis-lecture-lab 다섯 개를 보존한다.

빌드는 처음 한 번 2~5분 걸릴 수 있다. 이 시간에는 「공식 도구를 준비 중」이라고 진행 상태를 보여 준다. 분석 작업 제한과 Docker 빌드 시간은 서로 다른 값이다.

확인:

hermes mcp test kis-trade-mcp

화면에는 8개 도구가 보인다. API가 8개라는 뜻이 아니라 국내주식·해외주식·ETF/ETN 같은 8개 분야 안에 공식 호출 166개가 묶인 것이다. 이어서 AI에게 모의투자(env_dv=demo)로 삼성전자 현재가를 한 번 조회하게 한다. 주문은 하지 않는다.

토큰은 앱키당 1분에 1회다. 수업 랩과 공식 도구가 같은 키를 쓰므로 한 번에 한 손만 쓴다. 손을 바꾸면 1분 기다린다. EGW00133 이 나오면 그거다. 연타하면 계속 실패한다.

완료: 트레이딩 MCP 로 모의 시세 한 번, 또는 「Docker 없이」로 넘어갔다. 🧃 한입 · 트레이딩 손

4 · 코딩도우미 붙임 (둘러보기)

주문용이 아니다. 334를 찾기 위해서만.

npx -y @koreainvestment/kis-code-assistant-mcp

등록 이름 kis-code-assistant-mcp. 키 필요 없다. Docker 없이 되는 길이 있으면 그걸 둔다. 안 되면 이 스킬과 split.md 의 334/166 표로 둘러보기를 이어 간다. 트레이딩 MCP 는 이미 붙어 있어야 한다.

확인: 「국내주식 주문 API 찾아줘」를 👀 에만 묻는다. 샘플이 오면 된 것이다. 부르지 마라.

완료: 👀 가 찾기를 했거나, 표로 대신했다. 🧃 한입 · 코딩도우미

5 · 둘러보기 (조회 vs 액션)

한 질문씩. 학생이 사이트를 열지 않는다. 네가 👀(또는 표)와 🔧 목록을 본다.

1. "조회(읽기)로 보이는 것 다섯만 이름으로 말해 주세요. 예: 현재가, 호가, 잔고."
2. "액션(주문·정정·취소)으로 보이는 것 셋을 말해 주세요."
3. "334 안에만 있고 166으로 못 부르는 게 있으면, 그걸 고르면 주문이 나가나요?"

3의 정답: 안 나간다. 쓸 목록은 166 안에 있는 것만.

학생이 말한 조회·액션을 표로만 보여 준다. 수익을 단정하지 마라.

완료: 조회 다섯 · 액션 셋 · 「166 밖은 호출 안 됨」. 🧃 한입 · 둘러보기

6 · 고르기 (본인 트레이딩)

"지금 네 투자에 실제로 부르고 싶은 것을 고르세요. 조회 셋, 액션 하나. 166 안에 있는 것만. 왜 그것인지만 한 줄."

고른 것을 화면에 남긴다. 가능하면 내-투자-판단.md 의 「이번 주에 못 하는 것 / 나중에 붙이고 싶다」에 이름만 적는다. 칸을 지어내지 마라. 학생 말만.

완료: 조회 셋 · 액션 하나 · 이유 한 줄. 🧃 한입 · 고르기

7 · 조회 한 번 (트레이딩 MCP 만)

장중이고 키가 있을 때만. kis-trade-mcp 만. 코딩도우미·kis-lecture-lab 으로 대신하지 마라.

고른 조회 중 하나. env_dv=demo. 시세는 fid_input_iscd (종목코드). stock_name 인자로 inquire_price 를 부르면 공식 버그로 죽는다. 코드가 없으면 트레이딩 MCP 의 종목 찾기를 먼저.

숫자가 오면 한 줄로 읽는다. 수익 단정 금지. 15분이 넘으면 놓고 막힌 지점만.

완료: 트레이딩 MCP 조회 한 번, 또는 막힌 한 줄. 🧃 한입 · 공식 조회

8 · 주문은 다음 칸

이 스킬에서 confirm 주문까지 넣지 마라. 「고른 액션으로 모의주문」은 investment-habit-rules 가 한다. 그 스킬은 🔧 트레이딩 MCP 로만 평일 주문을 넣는다. 코딩도우미 금지.

homework 가 부르고 있으면 아래 붙여넣기를 보여 주지 마라. 한입만 하고 homework 로 돌아간다. 학생이 이 스킬만 직접 켰으면 끝낼 때 이 한 줄을 보여 주고 멈춘다.

.agents/skills/investment-habit-rules/SKILL.md 대로 내 투자 습관을 하나씩 물어봐 줘. 말한 것만 규칙으로 적고, 방금 고른 조회·액션과 그 규칙으로 첫 모의투자까지 가자. 주문 다음 회고도 이어서. 주문은 kis-trade-mcp 만. 코딩도우미로는 주문하지 마.

키가 없거나 🔧 를 못 붙였으면: 습관 문서만 채우고, 주문은 연습 계좌(kis-lecture-lab)이거나 「공식 도구 못 붙임」. 그것도 숙제다.

하지 말 것

• 코딩도우미로 order / 매수 / 매도
• env_dv=real · KIS_ENV=real
• kis-lecture-lab 을 공식 트레이딩으로 갈아끼우기 (토요일 손은 유지)
• 학생에게 git · Docker 명령을 외우게 하기. 네가 실행한다
• 334개 전부를 한 번에 읽히기. 찾기 → 고르기다
• Docker Desktop daemon을 2분 넘게 기다리기. 바로 랩으로 합류
• stdio 로 트레이딩 MCP 붙이기 — 2026-08-24 확인, 호출이 전부 죽는다. Docker + SSE 만
• 없어진 패치(FastMCP stateless_http · .env.live · KIS_PROD_TYPE)를 고치려 들기
• 설정 파일에 한글 자리표시자를 남긴 채 진행하기 (latin-1 에러)
• 수업 랩과 공식 도구를 동시에 부르기 (토큰 1분 1회를 서로 잡아먹는다)

에러는 .agents/skills/troubleshooting/SKILL.md.

2주차 미국 주식 참조 예제 — 평일에만

토요일 본편은 python agent/us_agent.py의 미국 연습 계좌다. 장 시간과 키에 기대지 않는다. 평일에 학생이 KIS 모의 키와 트레이딩 MCP를 붙였을 때만, 로컬에서 이미 승인한 주문 계획을 공식 해외주식 모의주문으로 옮길 수 있다.

순서를 바꾸지 않는다.

1. python agent/committee.py — AI 판단 제안. 주문 아님.
2. python agent/us_agent.py --adopt <제안번호> — 확정 스펙에서 주문 미리보기.
3. 학생이 종목·방향·수량·지정가·주문 계획 번호를 확인한다.
4. 학생이 승인한 그 값 그대로만 트레이딩 MCP overseas_stock / order에 전달한다.

미국 주식 모의주문 필수값:

api_type: order
env_dv: demo
ovrs_excg_cd: NASD | NYSE | AMEX
pdno: 승인된 티커
ord_qty: 승인된 수량
ovrs_ord_unpr: 승인된 지정가
ord_dv: buy | sell
ord_dvsn: "00"
ord_svr_dvsn_cd: "0"

모의 미국 주식 주문은 지정가(00)만 사용한다. 시장가·예약·정정취소로 바꾸지 않는다. AI가 티커, 방향, 수량, 가격을 다시 계산하거나 “더 좋아 보이는 값”으로 고치면 승인이 깨진 것이다. 주문하지 말고 로컬 미리보기부터 다시 한다.

이 경로에서도 env_dv=real은 멈춘다. 실계좌 안내는 lessons/9-마무리의 졸업 스위치로 넘기며, 이 스킬이 대신 켜거나 주문하지 않는다.