주식 추천 mcp 프로젝트 - 한국투자증권 API 기반 시세/수급 데이터 수집 MCP 서버 구현

이전 글에서 유튜브와 네이버 뉴스를 수집하는 Trend Scraper MCP 서버를 구현했었다. 이번에는 한국투자증권(한투) Open API를 활용하여 종목의 현재가, 차트, 기술지표, 외국인/기관 수급 데이터를 수집하는 mcp-market-data MCP 서버를 구현해보고자 한다.

이전 서버와 마찬가지로 서버는 수치만 반환하고, 판단과 해석은 LLM(Claude)에 위임하는 구조이다. (추후 주식에 대한 개인적 견해가 넓어지면 다양한 데이터 연동, 프롬프트에 해당 부분 가중치 설정 가능하도록 할 예정이다)

 

한국투자증권 Open API 발급

본 MCP 서버는 한국투자증권의 Open API를 사용한다. API를 사용하기 위해서는 사전에 계좌 개설과 API 키 발급이 필요하다. 간단히 절차를 정리하면 다음과 같다.

1단계: 계좌 개설

한국투자증권 모바일 앱(MTS)에서 비대면으로 계좌를 개설한다. 신분증만 있으면 되며, 지점 방문 없이 앱에서 바로 진행 가능하다.

2단계: KIS Developers 개발자 센터 가입

KIS Developers(https://apiportal.koreainvestment.com)에 접속하여 회원가입을 한다. 계좌 개설 시 카카오톡 알림톡으로 받은 ID(@로 시작)와 임시 비밀번호로 로그인할 수 있다.

3단계: API 키 발급

개발자 센터에서 앱 키(App Key)와 앱 시크릿(App Secret)을 발급받는다. 이 키들로 접근 토큰(Access Token)을 발급받고, 토큰을 이용하여 REST API를 호출하는 구조이다.

한투 Open API를 사용하는 이유는, 국내 증권사 중 유일하게 REST API 방식을 제공하기 때문이다. 키움증권 등 다른 증권사는 Windows OCX/COM 기반이라 OS 제약이 크지만, 한투 API는 OS에 관계없이 HTTP 요청만으로 호출할 수 있다.

발급받은 App Key, App Secret은 절대 외부에 공유하지 않도록 주의해야 한다.

 

제공 도구

mcp-market-data는 두 가지 도구를 제공한다.

도구역할

get_current_price_and_chart	종목의 현재가, 일봉/분봉 차트, 기술지표 반환
get_institutional_buying	외국인/기관/개인 수급(순매수) 데이터 반환

각 도구의 세부 구현을 살펴보자.

---

1. get_current_price_and_chart

이 도구는 특정 종목의 현재가, 차트 데이터, 기술지표를 한 번에 반환한다. 내부적으로 한투 API를 여러 건 호출하여 데이터를 조합하는 구조이다.

1.1 현재가

한투의 현재가 조회 API를 사용한다.

항목내용

API	inquire-price (FHKST01010100)
사용 필드	stck_prpr, prdy_clpr, acml_vol, stck_hgpr/lwpr/oprc, prdy_ctrt

반환되는 current 객체에는 다음 값들이 포함된다.

current: {
  price,        // 현재가
  change_pct,   // 전일 대비 등락률
  volume,       // 누적 거래량
  high,         // 고가
  low,          // 저가
  open          // 시가
}

1.2 일봉

일봉 데이터는 별도의 차트 API로 가져온다.

항목내용

API	inquire-daily-itemchartprice (FHKST03010100)
기간	미지정 시 최근 120일. FID_INPUT_DATE_1, FID_INPUT_DATE_2 필수

파싱 시 주의점이 있다. 한투 API 응답의 일봉 데이터는 body.output2 → output1 → output 순으로 배열을 탐색해야 한다. 응답 구조가 일관되지 않을 수 있기 때문에 이렇게 fallback 방식으로 처리한다.

각 행에서 사용하는 필드는 stck_clpr(종가)과 acml_vol(거래량)이다. 전일 거래량은 배열 뒤에서 두 번째 행의 acml_vol 값을 사용하며, 이를 통해 volume_ratio(거래량 비율)를 계산한다.

1.3 기술지표

일봉 데이터를 기반으로 기술지표를 계산하여 반환한다. 원시 수치만 제공하며, 판단이나 해석 문구는 포함하지 않는다.

항목내용

이동평균	ma5, ma20, ma60 (일봉 종가 기준)
거래량	volume_ratio (당일/전일 거래량 비율)
패턴	pullback_pct_vs_high (고가 대비 현재가 하락 %)
볼린저 밴드	bollinger_upper, bollinger_mid, bollinger_lower (20일 기준)

예를 들어 ma5가 ma20보다 위에 있으니 "골든크로스다"라는 판단은 서버가 하지 않는다. 수치만 넘기면 LLM이 알아서 해석한다.

1.4 chart_type 파라미터

chart_type에 따라 분봉 데이터를 추가로 가져올 수 있다.

값동작

day (기본)	일봉만 사용. minute 필드 없음
1min / 5min / 15min / 60min	분봉 API 호출 시도 → 파싱 성공 시에만 minute.candles 추가

주의할 점은 이평선과 볼린저 밴드는 항상 일봉 기준으로 계산된다는 것이다. chart_type을 5min으로 설정해도 기술지표는 일봉 데이터 기반이다. 분봉 데이터는 단순히 캔들 차트용 원시 데이터로만 제공된다.

---

2. get_institutional_buying

외국인, 기관, 개인의 순매수/순매도 데이터를 일별로 반환하는 도구이다.

2.1 API

항목내용

API	inquire-investor (FHKST01010900)
응답	body.output 배열 (일별 행)

2.2 응답 필드

각 행에서 사용하는 한투 공식 필드(snake_case)는 다음과 같다.

필드의미

stck_bsop_date	영업일
frgn_ntby_tr_pbmn	외국인 순매수 거래 대금
orgn_ntby_tr_pbmn	기관 순매수 거래 대금
prsn_ntby_tr_pbmn	개인 순매수 거래 대금

2.3 단위 변환

한투 API는 천원 단위로 값을 반환한다. MCP 서버에서 ×1000을 하여 원 단위로 변환한 뒤 반환하며, unit: "원"을 명시한다. 이 부분을 놓치면 금액이 1/1000로 축소되어 보이니 주의해야 한다.

2.4 반환 구조

{
  foreign: {
    net_buying_amt_sum: 총 순매수 합계,
    daily: [
      { date: "2025-02-28", net_buying_amt: 1500000000 },
      ...
    ]
  },
  institution: { ... },
  individual: { ... }
}

foreign, institution, individual 세 주체 각각에 대해 기간 합계(net_buying_amt_sum)와 일별 내역(daily)을 제공한다.

---

 

설정

환경 변수

한투 API 사용을 위해 .env에 다음 값을 설정한다.

변수설명

KIS_APP_KEY	한투 개발자 센터에서 발급받은 App Key
KIS_APP_SECRET	한투 개발자 센터에서 발급받은 App Secret

Claude Desktop 설정

{
  "mcpServers": {
    "market-data": {
      "command": "c:/Users/{사용자}/Desktop/mcp_for_finding_stocks/mcp-market-data/.venv/Scripts/python.exe",
      "args": [
        "c:/Users/{사용자}/Desktop/mcp_for_finding_stocks/mcp-market-data/main.py"
      ],
      "cwd": "c:/Users/{사용자}/Desktop/mcp_for_finding_stocks/mcp-market-data"
    }
  }
}

Trend Scraper와 함께 사용한다면 mcpServers 객체 안에 trend-scraper와 market-data를 나란히 등록하면 된다.

 

mcp-market-data는 한투 Open API를 통해 현재가, 일봉/분봉 차트, 기술지표(이평·볼린저), 외국인/기관 수급 데이터를 수집하는 MCP 서버이다.

이전에 구현한 mcp-trend-scraper(유튜브 + 뉴스)와 결합하면, LLM이 뉴스 트렌드 + 시세 데이터 + 수급 흐름을 종합적으로 분석할 수 있는 환경이 갖춰진다.

 

결과는 다음과 같다.

마지막에 나와있는 현재 내 결과는 내 프롬프트, 코드를 기반으로한 참고 자료일뿐, 투자 판단과 책은은 본인에게 있다는 점 유의해야한다.

 

추후에는 해당 데이터를 DB에 적재하는 방식을 고민해서 추가해 보려고 한다.

 

관련 소스 코드는 깃허브에서 확인가능하다.

https://github.com/SeongUk18/mcp_for_finding_stocks

GitHub - SeongUk18/mcp_for_finding_stocks