Korea Investment MCP Server (한국투자증권 MCP 서버)
이 프로젝트는 한국투자증권 OpenAPI를 활용하여 주식 및 파생상품 정보를 제공하는 MCP(Model Context Protocol) 서버입니다.
직접 만든 @jissp/nestjs-mcp-server 를 사용하였고, AI 모델이 한국투자증권의 실시간 주가 조회, 순위 분석, 투자자 매매 동향 등의 데이터를 직접 활용할 수 있게 합니다.
주요 특징
- NestJS 기반: 확장 가능하고 유지보수가 용이한 아키텍처
- @jissp/nestjs-mcp-server: 직접 만든 NestJS MCP 라이브러리 사용
- SSE(Server-Sent Events) 지원: 실시간 데이터 전송 최적화
- 다양한 금융 데이터: 주식, 선물, 옵션, 투자자 동향 등 포괄적인 API 제공
사전 준비 (Prerequisites)
- 한국투자증권 API 계정: 한국투자증권 API 포털에서 앱 키(App Key)와 앱 시크릿(App Secret)을 발급받아야 합니다.
- Node.js: v18 이상의 Node.js가 설치되어 있어야 합니다.
설치 및 설정
1. 프로젝트 설치
npm install2. 환경 변수 설정
프로젝트 루트에 .env 파일을 생성하거나, 시스템 환경 변수로 다음 값을 설정합니다.
KOREA_INVESTMENT_HOST=https://openapi.koreainvestment.com:9443
KOREA_INVESTMENT_APP_KEY=여러분의_APP_KEY
KOREA_INVESTMENT_APP_SECRET=여러분의_APP_SECRET
KOREA_INVESTMENT_USER_ID=여러분의_HTS_ID3. 프로젝트 빌드 및 실행
# 빌드
npm run build
# 서버 실행
npm run start:prod---
Claude Code에 설정하는 방법
이 서버는 SSE(Server-Sent Events) 방식을 통해 MCP 프로토콜을 지원합니다. Claude Code(CLI)에서 이 서버를 사용하려면 서버를 먼저 실행한 후 설정을 추가해야 합니다.
1. 서버 실행
터미널 또는 Docker 컨테이너를 시작하여 서버를 실행합니다.
npm run start:prod또는
docker compose up -d서버는 기본적으로 http://localhost:3000에서 동작하며, MCP 엔드포인트는 http://localhost:3000/mcp입니다.
2. Claude Code에 MCP 추가
새 터미널 창을 열고 Claude Code 설정 파일(~/.claude/settings.local.json)에 다음 내용을 추가하거나, claude mcp add 기능을 사용합니다.
방법 A: 설정 파일 직접 수정 ~/.claude/settings.local.json (또는 프로젝트의 .claude/settings.local.json) 파일을 열고 다음을 추가합니다:
{
"mcpServers": {
"korea-investment": {
"url": "http://localhost:3000/mcp"
}
}
}방법 B: Claude Desktop 설정 (MacOS/Windows) Claude Desktop 사용자의 경우, claude_desktop_config.json 파일에 추가합니다.
{
"mcpServers": {
"korea-investment": {
"url": "http://localhost:3000/mcp"
}
}
}---
데이터 관리 (코드 파일 업데이트)
주식 종목 코드나 업종 코드 등의 마스터 파일을 최신 상태로 유지하려면 다음 명령어를 실행합니다.
npm run update-mst이 명령어는 한국투자증권 서버에서 최신 마스터 파일을 다운로드하여 src/common/assets/*.json 파일들을 갱신합니다.
---
사용 방법
종목 정보 조회
❯ 삼성전자 종목에 대한 정보 조회해줘.
⏺ KoreaInvestmentMcp - search-stock-info (MCP)(PDNO: "005930", PRDT_TYPE_CD: "300")
⎿ {
"output": {
"pdno": "00000A005930",
… +71 lines (ctrl+o to expand)
⏺ 삼성전자 종목 정보를 조회했습니다.
주요 정보
기본 정보
- 종목명: 삼성전자
- 영문명: Samsung Electronics
- 종목코드: 005930 (KR7005930003)
- 종목구분: 주식(보통주)
시가총액 규모
- 상장주식수: 5,919,637,922주
- 시가총액: 778,046,685,000,000원 (약 778조)
- 액면가: 100원
현재 주가
- 현재가: 190,000원
- 기준일: 2026년 3월 11일
산업 분류
- 표준산업분류: 통신 및 방송 장비 제조업
- 지수분류:
- 시가총액 규모: 대형주
- 산업: 전기, 전자
거래 정보
- 거래 중지 여부: 거래 가능
- 행정 조치: 없음
- 전자증권: 적용됨
기타
- 상장일: 1975년 6월 11일
- KOSPI200 구성 여부: 포함
- 대차거래 가능: 가능
삼성전자는 한국 주식시장의 최대 규모 우량주이며, 현재 190,000원에 거래되고 있습니다.---
주요 기능 (Tools)
이 서버는 다음과 같은 도구(Tools)를 AI 모델에게 제공합니다.
1. 주식 및 지수 조회
inquire-index-price: 국내 업종별 지수의 현재가를 조회합니다.inquire-index-daily-price: 업종별 일자별 시세를 조회합니다.search-stock-info: 주식의 기본 정보를 조회합니다 (상품유형, 종목코드 등).intstock-multi-price: 여러 관심 종목의 현재가를 한 번에 조회합니다.
2. 투자자 매매 동향 및 시장 분석
investor-trade-by-stock-daily: 특정 종목의 일별 투자자 매매 추이를 분석합니다.investor-daily-by-market: 시장별(코스피/코스닥 등) 투자자 매매 동향을 조회합니다.hts-top-view: HTS 화면별 인기 조회 종목 순위를 제공합니다.
3. 통계 및 순위
volume-rank: 거래량 기준 종목 순위를 조회합니다.fluctuation-rank: 등락률 기준 종목 순위를 조회합니다.credit-balance-rank: 신용융자 잔고 상위 종목을 조회합니다.short-sale-rank: 공매도 잔고 상위 종목을 조회합니다.
4. 기타 현황
daily-credit-balance: 일별 신용융자 잔고 추이를 조회합니다.daily-short-sale: 일별 공매도 거래 현황을 조회합니다.daily-loan-trans: 일별 대차거래 현황을 조회합니다.
5. 파생상품
future-option-price: 선물/옵션 현재가 시세를 조회합니다.future-option-period-price: 선물/옵션의 기간별 시세를 조회합니다.
