KISPilot - 한국투자증권 Open API 웹 콘솔 & AI 에이전트(MCP) 만들기

October 6, 2026

KISPilot

⚠️ 안내

KISPilot은 비공식 개인 프로젝트입니다. 한국투자증권과 관계가 없으며 한국투자증권이 만들거나 검증하지 않았습니다. 이 소프트웨어는 투자 조언이 아니며, 주문·백테스트 결과로 생긴 손실에 대해 책임지지 않습니다 (MIT 라이선스, 무보증). 실전 계좌로 쓰기 전에 모의투자로 충분히 확인하세요.

한국투자증권(KIS) Open API를 이용해서 브라우저에서 쓰는 트레이딩 콘솔과 AI 에이전트용 MCP 서버를 하나로 묶은 도구를 만들었습니다. 이름은 KISPilot이고, PyPI에 올려 두었기 때문에 pip install kispilot 한 줄로 설치할 수 있습니다.

GitHub: dongju923/kispilot
PyPI: kispilot

이 글에서는 웹 콘솔의 각 화면을 직접 띄워서 캡처한 스크린샷과 함께 어떤 기능이 있는지 소개하겠습니다.

스크린샷은 모두 모의투자 모드로 찍었습니다. 화면에 나오는 계좌 잔고·보유 종목은 모의투자 계좌의 값입니다.

할 수 있는 것

구분	내용
조회	시세·호가·체결, 투자자·수급, 재무, 순위, 업종·지수, ETF, 계좌 잔고·손익 (KIS API 80여 개)
주문	현금·신용·예약 주문, 정정·취소
차트	1분~년봉, 이동평균·볼린저·일목균형표 등 지표, 보조 차트 30여 종
백테스트	기본 전략 11종 + 지표 157개로 만드는 커스텀 전략, 벤치마크 비교, 거래 내역
실시간	KIS 웹소켓 체결·호가 스트리밍
AI 에이전트	Claude, Cursor, VS Code Copilot, Gemini CLI, Codex 등에서 쓰는 MCP 도구 97개

기술 스택은 단순합니다. 백엔드는 Starlette + Uvicorn, 프론트엔드는 빌드 과정 없는 순수 HTML/JS이고, 차트는 TradingView Lightweight Charts를 썼습니다. 과거 일봉·분봉은 yfinance에서 가져오고 최근 거래일만 KIS API로 보강하는 방식이라, 긴 기간 차트나 백테스트도 API 호출 제한에 걸리지 않습니다.

설치와 실행

Python 3.11 이상이 필요합니다.

uv tool install kispilot      # 추천 (또는 pipx install kispilot)
pip install kispilot          # 일반 pip도 가능

키 등록 (처음 한 번)

KIS Developers에서 앱키·앱시크릿을 발급받은 뒤 아래 명령으로 등록합니다.

kispilot setup        # 실전 / 모의투자 / 둘 다 선택 → 앱키·시크릿·계좌 입력
kispilot status       # 등록 상태 확인 (값은 가려서 표시)

키는 .env 파일이 아니라 OS 키체인(Windows 자격 증명 관리자, macOS 키체인 등)에 저장됩니다. 입력할 때 화면에 보이지 않고, 저장하기 전에 실제로 토큰을 발급해 보면서 키가 맞는지 확인합니다.

kispilot 0.1.2
데이터 폴더   C:\Users\...\AppData\Local\kispilot
OS 키체인     WinVaultKeyring
MCP 실전 주문 꺼짐 (모의투자만)

[실전]
  앱키      PSxx************  (키체인)
  앱시크릿  등록됨  (키체인)
  계좌      1234****-01
  토큰 유효 · 15시간 26분 남음

웹 콘솔 실행

kispilot ui           # http://127.0.0.1:8000

같은 PC에서만 접속되도록 기본으로 127.0.0.1에 열립니다.

웹 콘솔 둘러보기

왼쪽 사이드바는 시장 / 종목 / 매매 / 전략 네 묶음으로 나뉘어 있고, 상단 바에는 종목 검색, 실시간 연결 상태, 장 운영 구간(정규장·NXT 프리/애프터마켓 등), 실전/모의 모드 전환 버튼이 있습니다. 각 카드 오른쪽 위의 회색 태그(inquire_price, inquire_balance 등)는 그 카드가 호출하는 KIS API 이름입니다. API를 공부하면서 쓰기에도 편하도록 일부러 노출해 두었습니다.

1. 대시보드

대시보드

처음 열리는 화면입니다. 한 화면에서 그날 시장 분위기와 내 계좌를 같이 볼 수 있게 구성했습니다.

주요 지수: KOSPI · KOSDAQ · KOSPI 200 현재값과 등락, 고객예탁금
내 계좌: 총 평가금액, 예수금, 손익, 보유 종목 요약
관심종목: 종목 화면에서 ☆ 버튼으로 추가한 종목의 시세를 한 번에 조회
순위 스냅샷: 상승률 / 하락률 / 거래량 / 체결강도 상위 종목
투자자별 순매수: 코스피·코스닥의 개인·외국인·기관 순매수와 당일 프로그램 매매
시장 뉴스: 주식 관련 기사와 공시

종목 검색

상단 검색창은 종목명이나 코드 일부만 입력해도 자동완성됩니다. 키보드에서 /를 누르면 바로 검색창으로 포커스가 이동합니다.

2. 시장·업종

시장·업종

지수 단위로 시장 전체를 보는 화면입니다.

KOSPI / KOSDAQ / KOSPI 200 지수 차트 (1분 ~ 년봉, 이동평균 · 보조 지표 지원)
지수 상세: 시가·고가·저가·거래대금과 상승/보합/하락 종목 수
예상 체결 지수: 장 시작·마감 동시호가 때의 예상 지수
업종별 시세: 업종을 등락률 순으로 정렬하고 상대 강도를 막대로 표시
투자자 매매동향(일별) 과 증시 자금(고객예탁금 · 신용융자잔고 · 미수금)
시장 뉴스 · 공시 전체 목록

3. 순위 분석

순위 분석

KIS가 제공하는 순위 API들을 한 화면에 모았습니다. 왼쪽에서 순위 종류를 고르고, 위쪽 필터로 조건을 바꿔 조회합니다.

시세: 등락률, 거래량, 체결강도, 호가잔량, 예상체결 등락
규모·재무: 시가총액, 재무비율, 수익자산지표, 시장가치
괴리·수급: 이격도, 우선주 괴리율, 신용잔고, 공매도

시장(전체/코스피/코스닥), 정렬 기준, 가격 범위, 최소 거래량을 지정할 수 있고, 투자경고·관리 종목이나 우선주, ETF·ETN을 빼고 볼 수도 있습니다. 각 행의 ☆을 누르면 바로 관심종목에 추가됩니다.

4. 종목 분석

종목 분석은 시세·호가 / 투자자·수급 / 재무·기업정보 세 개의 탭으로 나뉩니다. 상단 종목 헤더에는 현재가, PER·PBR, 52주 최고·최저가와 함께 매수 / 매도 버튼이 있어서 바로 주문 화면으로 넘어갈 수 있습니다.

시세·호가

종목 분석 - 시세·호가

캔들 차트 (1분 · 5분 · 30분 · 일 · 주 · 월 · 년)
10단계 호가와 체결 내역이 KIS 웹소켓으로 실시간 갱신됩니다. 상단의 실시간 칩을 누르면 일시정지/재개할 수 있습니다.
기간별 시세 (일/주/월)와 외국인 순매수

차트 위의 이동평균 / 차트 지표 / 보조 차트 드롭다운으로 지표를 켜고 끌 수 있습니다.

보조 차트 선택

보조 차트는 MACD, RSI, Stochastic, CCI, DMI·ADX, Aroon 등 30여 종이 추세 / 모멘텀 / 변동성 / 거래량으로 묶여 있고, 검색해서 고를 수 있습니다. 선택한 순서대로 가격 차트 아래에 쌓이고, 설정은 브라우저에 저장되어 다른 종목으로 넘어가도 그대로 유지됩니다.

투자자·수급

종목 분석 - 투자자·수급

외국인 · 기관 · 외국계 회원사 · 프로그램 순매수 요약 카드
일자별 투자자별 매매동향과 외인 소진율
당일 회원사(증권사) 매매 상위
프로그램 매매 (시간별 / 일별)
공매도 · 대차거래 추이

재무·기업정보

종목 분석 - 재무·기업정보

기업 기본정보 (업종, 상장일, 상장주식수, 자본금, 관리종목 여부 등)
재무제표: 손익계산서 / 재무상태표, 연간 / 분기 전환
투자 지표: ROE, 이익률, 증가율, 부채비율, 유동비율, EPS·BPS, EV/EBITDA 등을 수익성 · 안정성 · 기타로 묶어서 표시

5. ETF

ETF

ETF 전용 화면입니다. 예시는 KODEX 200입니다.

시장가, NAV, 괴리율, 추적오차율, 순자산총액, 구성 종목 수
차트와 함께 시장가 vs NAV 등락률 비교
NAV 비교 추이 (시간별 / 일별)
구성 종목: 비중 순으로 정렬하고 종목별 현재가 · 등락률 · 평가금액 표시

6. 주문

왼쪽부터 주문 입력 → 호가 → 미체결 · 체결 내역 순서로 배치했습니다.

매수 / 매도 / 정정·취소 탭, 주문 구분은 현금 / 신용 / 예약 중에서 선택
호가 유형은 지정가 · 시장가 · 조건부지정가 · 최유리/최우선지정가 등을 고를 수 있고, 실전 모드에서 애프터마켓(NXT 15:30–20:00) 시간에는 애프터마켓용 호가 유형으로 자동으로 바뀝니다.
가운데 호가창에서 가격을 클릭하면 주문 가격으로 바로 들어갑니다.
수량은 10% / 25% / 50% / 최대 버튼으로 주문 가능 금액 기준으로 채울 수 있습니다.
매도할 때 필요한 보유 수량 · 매도 가능 수량 · 평균 매입가 · 평가 손익도 같이 보여 줍니다.

주문 버튼을 누르면 바로 전송되지 않고 확인 창이 한 번 뜹니다.

주문 확인

종목, 구분, 가격, 수량, 예상 금액, 계좌(실전/모의)를 확인한 뒤 주문 전송을 눌러야 실제로 나갑니다.

7. 계좌

총 평가금액, 예수금(D+2), 주식 평가금액, 평가 손익, 순자산
보유 종목: 매입가 · 현재가 · 평가손익 · 수익률 · 비중
자산 구성: 종목별 · 예수금 비중
통합 증거금
손익 분석: 기간별 손익, 종목별 매매손익, 권리 현황

통합 증거금과 손익 분석은 KIS에서 실전 계좌만 지원하는 API라서, 모의 모드에서는 위 캡처처럼 “실전 계좌 전용 기능입니다”라는 안내가 나옵니다.

8. 백테스트

가장 공을 많이 들인 화면입니다. 왼쪽에서 전략 · 종목 · 기간 · 자본 · 리스크 관리 · 거래 비용을 설정하고 백테스트 실행을 누르면 오른쪽에 결과가 나옵니다. 실제 계산은 서버(Python)에서 합니다.

기본 전략

백테스트 - 기본 전략

미리 만들어 둔 기본 전략 11종 중에서 고르고 파라미터만 바꿔서 돌릴 수 있습니다.

전략	분류	설명
SMA 골든/데드크로스	추세	단기 이동평균이 장기 이동평균을 상향 돌파하면 매수, 하향 돌파하면 매도
52주 신고가 돌파	추세	종가가 N일(기본 252일) 최고가를 돌파하면 매수, 손절·익절로 청산
추세 돌파 후 이탈	추세	N일 고점 돌파 시 매수, 다시 고점 아래로 이탈하면 매도
모멘텀	모멘텀	최근 N일 수익률이 임계치를 넘으면 매수, 0 미만이면 매도
연속 상승·하락	모멘텀	N일 연속 상승 시 매수, M일 연속 하락 시 매도
강한 종가	모멘텀	종가가 당일 범위의 상위 구간(IBS)에 있으면 매수, 하위 구간이면 매도
RSI 평균회귀	평균회귀	RSI가 과매도(30) 아래로 들어가면 매수, 과매수(70) 위로 돌파하면 매도
이동평균 이격도	평균회귀	종가/SMA 비율이 매수 임계 이하면 매수, 매도 임계 이상이면 매도
단기 반전	평균회귀	종가가 N일 평균보다 M% 이상 낮으면 매수, 높으면 매도
변동성 축소 후 확장	변동성	ATR이 평균 이하로 줄어든 상태에서 일중 수익률이 임계치를 넘으면 매수
추세 필터 + 시그널	복합	추세선 위에서 상승 시 매수, 추세선 아래에서 하락 시 매도

결과 화면에는 다음 항목이 나옵니다.

성과 지표: 총수익률, CAGR, 최대 낙폭(MDD), 샤프 비율, 승률, 손익비, 평균 익절/손절
벤치마크 비교: KOSPI · KOSDAQ · KOSPI 200 지수를 같은 초기 자본으로 환산해서 전략과 나란히 비교
자산 곡선과 낙폭(Drawdown) 차트
매매 시점 차트: 보유 구간을 음영으로 칠하고 매수 / 신호 매도 / 손절 / 익절 / 트레일링 스탑을 마커로 구분
거래 내역: 매수·청산 신호일과 실제 체결일(다음 봉 시가), 청산 사유, 손익을 표로 정리하고 CSV로 내보내기

신호가 난 다음 봉 시가에 체결되도록 해서 미래 데이터를 쓰는 문제(look-ahead bias)를 피했고, 수수료 · 거래세 · 슬리피지도 반영합니다. 위 예시는 삼성전자에 5/20일 골든크로스 전략을 최근 5년 동안 돌린 결과입니다.

커스텀 전략

백테스트 - 커스텀 전략

커스텀 전략 탭에서는 코드를 쓰지 않고 조건을 조합해서 나만의 전략을 만들 수 있습니다.

지표 추가: 이동평균 · 추세 · 모멘텀 · 변동성 · 거래량 · 가격 · 캔들스틱 패턴까지 157개 지표 중에서 골라 파라미터를 지정
진입 / 청산 조건: sma_5 상향 돌파할 때 sma_20 같은 식으로 조건을 만들고, 여러 조건을 AND / OR로 묶음
- 비교 연산자: >, <, >=, <=, 상향 돌파, 하향 돌파, 같을 때
이 전략 저장: 저장해 두고 나중에 불러올 수 있습니다. 웹 콘솔과 MCP 서버가 같은 저장소를 쓰기 때문에, 여기서 만든 전략을 AI 에이전트에서 그대로 불러와 돌릴 수도 있습니다.

AI 에이전트에서 쓰기 (MCP)

KISPilot은 웹 콘솔과 같은 기능을 MCP(Model Context Protocol) 서버로도 제공합니다. 명령 한 줄로 AI 클라이언트에 등록할 수 있습니다.

kispilot install claude-desktop   # Claude Desktop 앱
kispilot install claude-code      # Claude Code
kispilot install cursor           # Cursor
kispilot install vscode           # VS Code (GitHub Copilot 에이전트 모드)
kispilot install gemini           # Gemini CLI
kispilot install codex            # OpenAI Codex

등록하면 AI에게 이런 식으로 요청할 수 있습니다.

“삼성전자 최근 5년 골든크로스(5/20) 백테스트, 손절 7% 익절 20%로 해줘”
“SK하이닉스 RSI랑 20일선 지금 얼마야?”
“거래대금 상위 30종목의 최근 3일 외국인 순매수 정리해줘”

도구는 97개이고, 자주 하는 작업은 프롬프트 템플릿으로 만들어 두었습니다.

프롬프트	하는 일
오늘 시장 브리핑	지수 · 투자자 수급 · 강한/약한 업종 · 등락률/거래량 상위 · 주요 뉴스
종목 종합 분석	시세 · 추세(이동평균·RSI·MACD·볼린저) · 수급 · 재무 · 긍정/위험 신호
백테스트 마법사	전략 선택 → 실행 → 지수 대비 해석 → 파라미터 비교 → 저장
전략 만들기	말로 설명한 아이디어 → 커스텀 전략 JSON → 검증 → 백테스트 → 저장
주문 도우미	장 구간 확인 → 시세·주문 가능 수량 → 주문 내용 확인 → (실전) 2단계 승인
보유 종목 점검	잔고 · 손익 · 종목별 추세/지표 · 쏠림 점검 (주문 안 함)

LLM과 대화하다 보면 응답이 길어져 컨텍스트를 금방 채우기 때문에, 조회 결과는 {cols, rows} 표 형식으로 줄이고 일자별 목록은 기본으로 최근 7줄만 돌려주도록 했습니다.

주문 안전장치

AI가 스스로 도구를 호출하기 때문에 MCP 쪽은 웹 콘솔보다 보수적으로 동작합니다.

주문 도구의 기본값은 모의투자입니다.
실전 주문은 사용자가 환경변수 KIS_ALLOW_REAL_ORDERS=1을 직접 넣어야 켜집니다.
켜져 있어도 바로 나가지 않습니다. 주문 내용과 확인 번호를 먼저 돌려주고, 사용자가 승인한 뒤 order_confirm을 호출해야 전송됩니다 (3분 안에, 1회용).

마치며

처음에는 KIS Open API를 공부하려고 API를 하나씩 호출해 보는 스크립트로 시작했는데, 쓰다 보니 차트 · 백테스트 · 실시간 시세까지 붙으면서 웹 콘솔이 되었고, 마지막에는 AI 에이전트에서도 쓸 수 있도록 MCP 서버까지 만들게 되었습니다.

증권사 HTS만큼 기능이 많지는 않지만, API 이름이 화면에 그대로 보이고, 백테스트 전략을 노코드로 만들고, 같은 기능을 AI에게 말로 시킬 수 있다는 점이 이 프로젝트의 차별점이라고 생각합니다. 관심 있으신 분은 모의투자 계좌로 한번 사용해 보시고, 버그나 개선 의견은 GitHub Issues에 남겨 주세요.

Twitter Facebook LinkedIn

안동주