stock-mcp-server

uchegug-blip/stock-mcp-server

3.2

If you are the rightful owner of stock-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This is a stock information retrieval MCP server integrated with the Korea Investment & Securities API.

Tools
3
Resources
0
Prompts
0

📈 Stock MCP Server

한국투자증권 API를 연동한 주식 정보 조회 MCP(Model Context Protocol) 서버입니다.

Claude Desktop, Cline 등 MCP를 지원하는 AI 애플리케이션에서 주식 시세 조회, 계좌 잔고 확인, 주문 실행 등을 수행할 수 있습니다.

✨ 주요 기능

  • 🔍 주식 현재가 조회 - 실시간 시세, 등락률, 거래량 확인
  • 💰 계좌 잔고 조회 - 총 자산, 예수금, 보유 종목 확인
  • 📊 주문 실행 - 매수/매도 주문 (시장가/지정가)
  • 🔐 안전한 인증 - 환경 변수를 통한 API 키 관리
  • 📝 타입 안전성 - TypeScript로 작성된 완전한 타입 지원

🚀 빠른 시작

1. 필수 요구사항

  • Node.js 18 이상
  • 한국투자증권 계좌 (실전투자 또는 모의투자)
  • 한국투자증권 Open API 앱 키 발급

2. 설치

# 저장소 클론
git clone https://github.com/yourusername/stock-mcp-server.git
cd stock-mcp-server

# 의존성 설치
npm install

# 빌드
npm run build

3. 환경 설정

.env.example 파일을 복사하여 .env 파일을 생성하고, 본인의 정보를 입력합니다:

cp .env.example .env

.env 파일 내용:

# 한국투자증권 API 설정
KIS_APP_KEY=your_app_key_here
KIS_APP_SECRET=your_app_secret_here
KIS_ACCOUNT_NO=12345678-01
KIS_PRODUCT_CODE=01

# 환경 (real: 실전투자, virtual: 모의투자)
KIS_ENV=virtual

4. MCP 설정

Claude Desktop

claude_desktop_config.json 파일에 다음 설정을 추가합니다:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

설정 내용:

{
  "mcpServers": {
    "stock": {
      "command": "node",
      "args": [
        "D:/Documents/프로젝트/stock-mcp-server/build/index.js"
      ]
    }
  }
}

⚠️ 경로 주의: 본인의 프로젝트 경로로 수정하세요!

Cline (VS Code Extension)

Cline 설정에서 MCP 서버를 추가합니다:

{
  "mcpServers": {
    "stock": {
      "command": "node",
      "args": [
        "/absolute/path/to/stock-mcp-server/build/index.js"
      ]
    }
  }
}

5. Claude Desktop 재시작

설정을 완료한 후 Claude Desktop을 재시작하면 🔨 아이콘에서 Stock MCP Server를 확인할 수 있습니다.

📚 사용 방법

주식 현재가 조회

삼성전자 현재가 알려줘

005930 주식 정보 조회해줘

계좌 잔고 조회

내 계좌 잔고 보여줘

보유 종목 확인해줘

주문 실행

삼성전자 10주 시장가로 매수해줘

005930 종목 50000원에 20주 매도 주문해줘

🔧 사용 가능한 도구

1. get_stock_price

주식의 현재가 정보를 조회합니다.

파라미터:

  • symbol (string, 필수): 종목 코드 (예: "005930")

응답 예시:

📊 삼성전자 (005930)

🔴 현재가: 75,000원
🔴 등락: +1,500원 (+2.04%) 상승

📈 시가: 74,000원
📈 고가: 75,500원
📉 저가: 73,800원

💹 거래량: 15,234,567주
💰 거래대금: 1,142,592,525,000원

2. get_account_balance

계좌의 잔고 정보를 조회합니다.

파라미터: 없음

응답 예시:

💼 계좌 잔고 현황

💰 총 자산: 10,000,000원
💵 예수금: 5,000,000원
📈 주식 평가액: 5,000,000원
💸 매입금액: 4,800,000원

🔴 평가 손익: +200,000원
🔴 수익률: +4.17%

📊 보유 종목 (1개)
==================================================

1. 삼성전자 (005930)
   보유: 100주 (평균 48,000원)
   현재가: 50,000원
   🔴 손익: +200,000원 (+4.17%)

3. place_order

주식 매수/매도 주문을 실행합니다.

파라미터:

  • symbol (string, 필수): 종목 코드
  • quantity (number, 필수): 주문 수량
  • orderType (string, 필수): "buy" 또는 "sell"
  • price (number, 선택): 지정가 (생략 시 시장가)
  • priceType (string, 선택): "market" 또는 "limit" (기본값: "market")

응답 예시:

✅ 매수 주문이 접수되었습니다.
주문번호: KRX202501080001
주문시각: 2025-10-08T09:15:30Z

🏗️ 프로젝트 구조

stock-mcp-server/
├── src/
│   ├── index.ts              # 메인 서버
│   ├── types.ts              # 타입 정의
│   ├── tools/                # MCP 도구 함수
│   │   ├── stockPrice.ts
│   │   ├── accountBalance.ts
│   │   └── placeOrder.ts
│   └── utils/                # 유틸리티
│       ├── config.ts         # 설정 관리
│       ├── validator.ts      # 데이터 검증
│       ├── formatter.ts      # 포맷팅
│       └── kisClient.ts      # API 클라이언트
├── build/                    # 컴파일된 파일
├── tests/                    # 테스트
├── .env.example              # 환경 변수 예시
├── package.json
├── tsconfig.json
└── README.md

🔐 보안

  • ⚠️ 절대 .env 파일을 Git에 커밋하지 마세요
  • 🔒 API 키는 환경 변수로만 관리됩니다
  • 🛡️ 모의투자로 먼저 테스트하는 것을 권장합니다
  • 💡 실전투자 사용 시 신중하게 사용하세요

.gitignore에 다음 내용이 포함되어 있는지 확인하세요:

.env
.env.local
.env.*.local

🧪 개발

개발 모드 실행

# TypeScript 실시간 컴파일
npm run dev

빌드

npm run build

테스트

npm test

📖 한국투자증권 API 키 발급

  1. 한국투자증권 계좌 개설
  2. KIS Developers 접속
  3. 앱 등록 및 API 키 발급
    • 앱 키 (App Key)
    • 앱 시크릿 (App Secret)
  4. 계좌번호 확인 (예: 12345678-01)

모의투자 계좌 개설

  • 모의투자 신청
  • 실전투자와 동일한 API 사용 가능
  • 가상 자금으로 안전하게 테스트 가능

🐛 문제 해결

Claude Desktop에서 서버가 보이지 않아요

  1. claude_desktop_config.json 경로가 정확한지 확인
  2. JSON 문법 오류가 없는지 확인 (쉼표, 중괄호 등)
  3. Claude Desktop 완전히 종료 후 재시작
  4. 로그 확인:
    • Windows: %APPDATA%\Claude\logs
    • macOS: ~/Library/Logs/Claude

API 인증 오류가 발생해요

  1. .env 파일이 프로젝트 루트에 있는지 확인
  2. API 키가 정확한지 확인 (공백 없이 입력)
  3. KIS_ENV 설정 확인 (real/virtual)
  4. 한국투자증권 API 포털에서 키 상태 확인

종목 코드를 모르겠어요

주요 종목 코드:

  • 삼성전자: 005930
  • SK하이닉스: 000660
  • NAVER: 035420
  • 카카오: 035720
  • 현대차: 005380
  • LG화학: 051910

네이버 증권이나 한국거래소에서 종목 코드를 검색할 수 있습니다.

🗺️ 로드맵

v0.1.0 (현재)

  • 기본 MCP 서버 구조
  • 타입 정의
  • 유틸리티 함수
  • 한국투자증권 API 연동

v0.2.0 (예정)

  • 실시간 시세 조회
  • 호가 정보 조회
  • 체결 내역 조회
  • 미국 주식 지원

v1.0.0 (목표)

  • 완전한 API 연동
  • 단위 테스트
  • 에러 처리 강화
  • 성능 최적화

🤝 기여

기여를 환영합니다! 다음 방법으로 참여해주세요:

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📝 라이선스

MIT License - 자유롭게 사용, 수정, 배포할 수 있습니다.

📧 연락처

작성자: 성철
프로젝트: GitHub Repository

🙏 감사의 말

📚 참고 자료

⭐ 이 프로젝트가 유용하다면 Star를 눌러주세요!

주의사항: 이 소프트웨어는 교육 및 개인 사용 목적으로 제공됩니다. 실제 투자에 사용할 경우 발생하는 손실에 대해 개발자는 책임지지 않습니다.