MCP API로 주식 Top10 PER/PBR 비교 웹앱 만들기 도전기

소개

9-15일 웹서핑 중 한국투자증권에서 MCP API를 공개했다는 뉴스(https://news.hada.io/topic?id=23084)를 보게 되었어요. 마침 MCP라는 개념도 막 배우던 참이라 반가운 마음에 "나도 이걸로 뭔가 만들어볼까?" 하는 생각이 들었죠.

https://news.hada.io/topic?id=23084

요즘 주식시장도 활황이니, 너무 복잡한 기능 말고 간단한 MVP로 시작해보자 싶었어요. 그래서 선택한 주제는 바로!

"오늘 상승률 상위 10개 종목의 PER, PBR 비교해줘"

👉 잠깐 여기서 PER과 PBR은 주식 투자자들이 많이 참고하는 대표적인 지표예요.

PER (Price to Earnings Ratio, 주가수익비율): 주가를 주당순이익(EPS)으로 나눈 값입니다.
- 낮을수록 현재 주가가 이익에 비해 저렴하다고 판단되어 저평가로 보기도 해요.
- 단, 업종에 따라 '적정 PER'이 다르기 때문에 비교 기준이 중요해요.
PBR (Price to Book Ratio, 주가순자산비율): 주가를 주당순자산(BPS)으로 나눈 값입니다.
- 1 이하이면 보통 '자산가치보다 싸다'고 해석되며, 저평가로 인식되곤 해요.
- 반대로 너무 낮으면 사업성 자체에 의심을 받는 경우도 있으니 주의가 필요합니다.

GPT랑 상의해서 PRD도 작성하고, 바로 실전 개발에 들어갔습니다 💪

진행 방법

사용한 도구들

💻 개발툴: React + Vite, Git, GitHub, Cursor, ClaudeCode
🧠 gpt 도움: 대화내용
🎨 디자인: Google AI Studio 앱 빌더 (앱 링크 - Google AI Studio에서 만든 디자인 보기)
📡 데이터/API: 한국투자 MCP API 공식 문서 보기

작업 흐름

PRD 작성: GPT 도움 받아 주식 Top10 PER/PBR 비교 웹앱 PRD를 작성함

📑 PRD: 주식 Top10 PER/PBR 비교 웹앱
1. 배경 및 목적
투자자들은 매일 시장 상위 종목(시가총액 기준)의 핵심 지표를 빠르게 확인하고 싶어 함.
특히 PER(주가수익비율) 과 PBR(주가순자산비율) 은 가장 기본적이면서도 직관적인 투자 지표임.
본 웹앱은 MCP 서버(예: KIS API 기반 MCP, Paper Trading MCP 등)를 통해 데이터를 불러와 단순 비교 차트로 제공하는 MVP.

2. 주요 목표
MCP 서버와 연동하여 오늘의 Top10 종목 데이터를 확보
각 종목의 PER, PBR 지표를 조회
직관적인 막대 차 시각화로 제공
사용자는 별도의 클릭 없이 페이지 접속 시 즉시 결과 확인 가능

3. 사용자 시나리오
투자자 A는 웹페이지에 접속 → “오늘의 Top10 PER/PBR 비교”라는 타이틀 확인 →
두 개의 막대 차트(PER, PBR)를 통해 상위 10개 기업의 상대적 밸류에이션을 한눈에 파악.
추가 기능: 표 형태로 원자료(티커, 종목명, PER, PBR) 제공.

4. 기능 요구사항
데이터 수집
MCP Tool: list-top10 → 오늘의 상위 10개 종목 티커 반환
MCP Tool: get-fundamentals → PER, PBR 데이터 반환
Mock 데이터 fallback 지원(실서버 연결 전용)
데이터 처리
PER, PBR 값이 없는 경우 null → 0으로 치환 또는 “-” 표시
상위 10개만 추려서 배열화
프론트엔드(UI)
헤더: “오늘의 Top10 PER/PBR 비교”
차트 영역
차트 1: PER 막대그래프
차트 2: PBR 막대그래프
표 영역
종목코드, 종목명, PER, PBR 표시
성능/보안
데이터 호출은 서버사이드 API 라우트에서 MCP 호출 후 JSON 반환
API Key 등 민감 정보는 .env 관리

5. 기술 요구사항
프론트엔드: Next.js(App Router), TailwindCSS, Recharts
백엔드: MCP 클라이언트 SDK (@modelcontextprotocol/sdk), API Route

MCP 서버:
KIS API 기반 MCP (실거래/실데이터)
Open Paper Trading MCP (가상매매/테스트용)

6. 비기능 요구사항
단순성: 페이지 진입 즉시 결과 표시 (별도 검색/입력 불필요)
확장성: 향후 Top20, 다른 지표(ROE, EPS 등) 비교 기능 추가 가능
이식성: MCP 서버만 교체하면 해외 데이터/모의투자 데이터로 확장 가능

7. 성공 지표 (KPI)
초기 MVP: “페이지 로딩 시 Top10 PER/PBR 비교가 정상적으로 표시되는가?”
사용자 관점: “3초 이내에 데이터가 로딩되고 시각화되는가?”

디자인: 구글 AI Studio에서 초안 생성 → 너무 어두워서 톤 변경 요청함
Git 연동: 구글 스튜디오 코드를 GitHub에 연결하고 Cursor에서 레포 불러옴
개발 시작: ClaudeCode에게 프롬프트 주며 단계별로 작업 진행
한투증권 MCP 설치: 터미널 명령어 안돼서 Claude 채팅창에 설치 명령어 줌 → 설치 완료
```
claude mcp add --transport http kis-open-api-kis-code-assistant-mcp "https://server.smithery.ai/@KISOpenAPI/kis-code-assistant-mcp/mcp"
```
API 연동: MCP API 연동 시도 → 데이터 수집 및 처리
문제 해결: 데이터 오류, 화면 미표시, 값 누락 등 반복 디버깅
.env 설정: API Key 환경변수로 이동 후 재실행
실데이터 적용: 삼성전자, SK하이닉스 등 실제 PER/PBR 값으로 비교 성공

클로드 코드 주요 프롬프트 전체

>cluade.md파일에 규칙을 설정할 거야. 중요한 업데이트가 있으면 별도의 파일을 만들어서 기록하고 업데이트해

> git 초기화 해줘

> @stock_top10_per_pbr_prd.md 파일 따라 순차적으로 개발을 시작하고 깊게 생각하면서 해줘. 필요한게 있으면 나에게 물어보고, todo.md파일에 니가 한 일을 기록하면서 해줘 

> 현재 React+Vite 구조를 유지하고 서버를 활용해서 실제 주식정보를 가져와.  

> 지금 단계까지 내용을 실행해 보자 

> 이게 현재 데이터를 불어온거 맞아? 

> 연동해

> [Image #1]화면이 보이지 않는다. 해결해라

> 데이터 연동이 안되는거 같아. 삼성전자는 per는 17.1 이고 pbr은 1.3이야 오류를 찾아서 해결해

> 한국투자 코딩도우미 Mcp 가 현재 시가 총액 상위 10개 항목의 per과 pbr을 불러오지 못하고 있다. 오류의 원인을 찾아서 해결해라

> 리액트 서버를 실행해 보면 여전히 주식정보를 제대로 불러 오지 못하는 오류가 있어 sk하이닉스의 per는 8.4 pbr은 2.6야 오류를 수정하라

> mock 데이터 사용하지 말고 api를 통해서 불어온 데이터를 받아와

> .env에 api키를 넣었다. 서버를 재실행 하라

> [Image #1]서버를 실행하면 데이터가 나오지 않거나 부정확한 정보가 표현된다. api가 연동이 된것인지 확인하고 종목의 per와 pbr을 정확하게 불러와라.

> 좋아. api는 잘 불러왔다. 그럼 이제 이전 날짜도 종가를 기준으로 per와 pbr을 검색하는 기능을 만들어라

결과와 배운 점

.env 설정의 중요성을 느낌 😅 (API 키 미설정으로 한참 헤맴)--이미 prd에 적혀있었지만, 몰랐음~ㅎㅎ prd의 꼼꼼한 검토의 중요성!!!!
한국투자 MCP API 사용하려면 계좌 개설 필수 → 뜻하지 않게 주식계좌 실제 개설함
Git vs GitHub: Git은 로컬, GitHub는 클라우드라는 개념적 차이 확실히 이해함. 로컬에 저장한 내역입니다. 아직 git허브에 push는 하지 않은 상태~
서버를 실행하기 전에 api서버도 실행을 해야하나봐요~주식정보를 잘 못불어와서 다시 불어오라고 하니까 api서버를 실행해야 한다네요~이거 매번 자동으로 api서버 실행안하면 불편할것 같긴한데, 우선 mvp니~별도 수정은 안했습니다.
실제 데이터 기반 웹앱 만들기 완성!