KISPilot

한국투자증권 Open API를 AI 에이전트(MCP) 와 웹 콘솔에서 쓰기 위한 도구 모음입니다.

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

할 수 있는 것

• 조회 — 시세·호가·체결, 투자자·수급, 재무, 순위, 업종·지수, ETF, 계좌 잔고·손익 (KIS API 80여 개)
• 주문 — 현금·신용·예약 주문, 정정·취소 (에이전트는 모의투자가 기본, 실전은 2단계 확인)
• 차트 — 1분~년봉, 이동평균·볼린저·일목균형표 등 지표, 보조 차트 30여 종
• 백테스트 — 기본 전략 11종 + 지표 157개로 만드는 커스텀 전략, 벤치마크 비교, 거래 내역, 전략·파라미터 여러 개 한 번에 비교, 여러 종목 포트폴리오(비중 + 리밸런싱)
• 실시간 — KIS 웹소켓 체결·호가 (웹 콘솔)

설치

Python 3.11 이상이 필요합니다.

추천 — 도구 전용 환경에 설치되고 kispilot 명령이 PATH 에 자동으로 등록됩니다.

uv tool install kispilot      # 또는: pipx install kispilot

일반 pip 로도 설치할 수 있습니다. 가상환경·conda 를 켠 상태에서 설치하면 그 환경을 켰을 때만 kispilot 명령이 보입니다.

pip install kispilot

설치 없이 바로 실행 (uv 필요):

uvx kispilot ui

버전별 변경 내용은 Releases 에 있습니다.

소스에서 개발용으로 설치하려면:

git clone https://github.com/dongju923/kispilot
cd kispilot
pip install -e .

키 등록 (처음 한 번)

KIS Developers에서 앱키·앱시크릿을 발급받은 뒤 터미널에서 실행합니다.

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

• 앱키·시크릿은 OS 키체인(Windows 자격 증명 관리자, macOS 키체인, Linux Secret Service)에 저장됩니다. 파일에 평문으로 남지 않습니다.
• 입력은 화면에 보이지 않고, 저장 전에 실제로 토큰을 발급해 키가 맞는지 확인합니다.
• 키를 AI 채팅창에 붙여넣지 마세요. 채팅 내용은 대화 기록과 AI 서비스 쪽에 남습니다.
• 지우려면 kispilot logout (키체인 삭제 + 토큰 폐기).

키체인을 쓸 수 없는 환경(서버 등)에서는 환경변수로 넣을 수 있습니다. 환경변수가 키체인보다 먼저 쓰입니다. 변수 이름은 .env.example을 참고하여, .env 파일을 새로 생성하세요.

웹 콘솔

kispilot ui           # http://127.0.0.1:8000

대시보드, 시장·업종, 순위, 종목 분석(차트·호가·수급·재무), ETF, 주문, 계좌, 백테스트 화면이 있습니다. 같은 PC에서만 접속되도록 127.0.0.1에 열립니다.

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

KISPilot 은 공개 표준인 MCP(Model Context Protocol) 서버라서, 내 PC 에서 MCP 서버를 실행할 수 있는 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 (CLI · IDE 확장)

• 등록한 뒤 해당 앱을 다시 시작하면 연결됩니다.
• 지금 설치된 kispilot 실행 파일의 전체 경로로 등록하므로 PATH 설정이 필요 없습니다.
• 설정 파일은 바꾸기 전에 <파일이름>.bak-날짜 로 백업하고, 다른 항목은 건드리지 않습니다. 주석이 들어간 JSON 처럼 읽을 수 없는 파일은 고치지 않고 알려 줍니다 (아래 "직접 설정" 참고).
• 실전 주문은 꺼진 상태로 등록됩니다. 켜려면 --allow-real-orders 를 붙입니다 (아래 안전장치 참고).
• 바뀔 내용만 보려면 --dry-run, 설정 파일 위치를 바꾸려면 --config <경로>, 해제는 kispilot uninstall <대상>.
• 동작 확인: kispilot mcp --check

ChatGPT·Gemini 웹처럼 브라우저에서 쓰는 서비스는 내 PC 의 프로그램을 실행할 수 없어서 지금은 연결되지 않습니다 (인터넷에 공개된 원격 MCP 서버가 필요합니다).

MCP 도구 (99개)

예: "삼성전자 최근 5년 골든크로스(5/20) 백테스트, 손절 7% 익절 20%로 해줘", "같은 기간에 이평 5/20, 10/60, 20/120 비교해 줘", "삼성전자 40 · SK하이닉스 30 · NAVER 30 으로 분기마다 리밸런싱하면 5년 동안 어땠어?", "SK하이닉스 RSI랑 20일선 지금 얼마야?"

대화 길이를 아끼도록 KIS 조회 도구는 응답을 줄여서 돌려줍니다.

• 목록은 {cols, rows} 표 형식으로 옵니다 (행마다 필드 이름을 반복하지 않음).
• 일자별 목록은 기본으로 최근 7줄만 옵니다. 순위·잔고처럼 날짜가 없는 목록, 분봉·체결 같은 장중 목록, 시작일을 지정하는 조회는 전부 옵니다.
• 공통 인자 rows(줄 수, 0 이면 전부)와 fields(남길 필드)로 에이전트가 필요한 만큼만 받습니다.

MCP 프롬프트 (작업 템플릿)

자주 하는 작업의 진행 순서를 담은 템플릿입니다. 고르는 방법은 클라이언트마다 다릅니다: Claude Desktop 은 입력창의 + 메뉴, Claude Code 는 /kispilot:<이름>, Gemini CLI 는 /<이름>, VS Code 는 /kispilot.<이름>. 프롬프트를 지원하지 않는 클라이언트도 있는데, 그때는 "오늘 시장 브리핑해 줘" 처럼 말로 요청하면 됩니다. 칸을 비워 두면 대화로 물어봅니다.

{
  "mcpServers": {
    "kispilot": {
      "command": "<kispilot 실행 파일 전체 경로>",
      "args": ["mcp"],
      "env": { "KIS_ALLOW_REAL_ORDERS": "0" }
    }
  }
}

{
  "servers": {
    "kispilot": {
      "type": "stdio",
      "command": "<kispilot 실행 파일 전체 경로>",
      "args": ["mcp"],
      "env": { "KIS_ALLOW_REAL_ORDERS": "0" }
    }
  }
}

[mcp_servers.kispilot]
command = "<kispilot 실행 파일 전체 경로>"
args = ["mcp"]
startup_timeout_sec = 30

[mcp_servers.kispilot.env]
KIS_ALLOW_REAL_ORDERS = "0"

주문 안전장치 (에이전트)

AI 모델이 스스로 도구를 부르기 때문에 웹 콘솔보다 보수적으로 동작합니다.

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

데이터 출처와 저장 위치

• 과거 일봉·분봉: yfinance (Yahoo Finance, 개인적·연구 목적 이용 권장), 최근 거래일은 KIS API로 보강
• 토큰 캐시·종목 마스터·커스텀 전략: 사용자 데이터 폴더 (kispilot status 에 표시, 환경변수 KISPILOT_HOME 으로 변경)
• 차트: TradingView Lightweight Charts (Apache-2.0)

참고

• 한국투자증권 Open API — 모든 시세·계좌·주문 기능은 이 API 를 호출합니다.
• koreainvestment/open-trading-api — 백테스트 기본 전략 구성(프리셋 종류)과 종목 마스터 파일 형식(필드 폭·열 이름)을 참고했습니다.

라이선스

MIT