📊 MCP Market Statistics Server

한국 주식시장의 종합적인 통계 데이터와 시장 분석 정보를 제공하는 MCP(Model Context Protocol) 서버입니다.

CI/CD Pipeline codecov Python 3.11+ License: MIT

✨ 주요 기능

🏢 시장 데이터

실시간 지수 현황: KOSPI, KOSDAQ, KOSPI200 등
시장 전체 통계: 시가총액, 거래대금, 상승/하락 종목 수
52주 신고가/신저가 통계 및 분석

📈 섹터별 분석

업종 로테이션 분석 및 추적
섹터별 밸류에이션 비교
리더/래거드 종목 식별

💰 투자자 동향

개인/기관/외국인 매매 동향
프로그램 매매 현황 분석
스마트머니 추종 지표

🌊 시장 심리 지표

Fear & Greed Index (한국판)
Put/Call Ratio 분석
변동성 지수 (VKOSPI)
뉴스 감성 분석

🔍 고급 분석

시장 이상 징후 탐지 - AI 기반 이상 패턴 감지
시장 국면 판단 - 불장/곰장/횡보장 구분
유동성 분석 - 시장 깊이 및 유동성 측정
상관관계 매트릭스 - 자산 간 상관관계 분석
패턴 인식 - 차트 패턴 및 기술적 지표 분석
다중 시간대 분석 - 여러 타임프레임 통합 분석
감정 분석 - 뉴스 및 소셜미디어 감정 분석
가격 예측 - 머신러닝 기반 가격 예측
리스크 평가 - 포트폴리오 리스크 분석

🚀 빠른 시작

사전 요구사항

Python 3.11 이상
TimescaleDB
Redis
Docker (선택사항)

설치

저장소 클론
git clone https://github.com/your-org/mcp-market-statistics.git cd mcp-market-statistics
가상환경 생성 및 활성화
python -m venv venv source venv/bin/activate # Linux/Mac # 또는 venv\Scripts\activate # Windows
의존성 설치
make install # 또는 pip install -r requirements.txt
환경 변수 설정
cp .env.example .env # .env 파일을 편집하여 데이터베이스 및 API 설정

Docker를 이용한 실행

# 이미지 빌드 및 실행 make docker-run # 또는 직접 실행 docker-compose up -d

개발 모드 실행

# 개발 서버 시작 make dev-server # 테스트 실행 make test # 코드 포맷팅 make format # 보안 검사 make security

🛠️ 개발 가이드

프로젝트 구조

mcp-market-statistics/ ├── src/ # 소스 코드 │ ├── server.py # MCP 서버 메인 │ ├── tools/ # MCP 도구 정의 │ ├── collectors/ # 데이터 수집 │ ├── analytics/ # 고급 분석 엔진 │ │ ├── advanced_pattern_recognition.py │ │ ├── multi_timeframe_analyzer.py │ │ ├── correlation_engine.py │ │ ├── price_predictor.py │ │ ├── sentiment_analyzer.py │ │ ├── market_anomaly_detector.py │ │ └── risk_assessment_engine.py │ ├── analyzers/ # 시장 분석기 │ ├── calculators/ # 계산 모듈 │ ├── models/ # 데이터 모델 │ ├── utils/ # 유틸리티 │ ├── exceptions.py # 커스텀 예외 │ └── config.py # 설정 관리 ├── tests/ # 테스트 코드 ├── .github/workflows/ # CI/CD 파이프라인 ├── requirements.txt # Python 의존성 ├── Dockerfile # Docker 이미지 빌드 ├── docker-compose.yml # 서비스 오케스트레이션 └── Makefile # 개발 명령어

테스트 작성

이 프로젝트는 TDD(Test-Driven Development) 방법론을 따릅니다.

# 모든 테스트 실행 make test # 커버리지와 함께 테스트 make test-cov # 통합 테스트 실행 make test-integration

코드 품질

# 린팅 실행 make lint # 코드 포맷팅 make format # 보안 검사 make security # 모든 체크 실행 make ci-test

🔧 설정

환경 변수

변수명	설명	기본값
`TIMESCALE_DB_HOST`	TimescaleDB 호스트	localhost
`TIMESCALE_DB_PORT`	TimescaleDB 포트	5432
`TIMESCALE_DB_NAME`	데이터베이스 이름	market_stats
`REDIS_HOST`	Redis 호스트	localhost
`REDIS_PORT`	Redis 포트	6379
`LOG_LEVEL`	로그 레벨	INFO
`KRX_API_KEY`	KRX API 키	-

데이터베이스 스키마

데이터베이스 스키마를 초기화하려면:

make db-setup

📡 API 사용법

MCP 도구 목록

기본 시장 데이터

get_market_overview - 시장 전체 현황
get_sector_statistics - 섹터별 통계
get_investor_flows - 투자자별 매매 동향
get_market_breadth - 시장 폭 지표

고급 분석 도구

analyze_advanced_patterns - 고급 패턴 인식 및 분석
analyze_multi_timeframe - 다중 시간대 분석
analyze_correlations - 상관관계 엔진
predict_prices - AI 기반 가격 예측
analyze_sentiment - 감정 분석
detect_anomalies - 시장 이상 징후 탐지
assess_risks - 리스크 평가
get_market_sentiment - 시장 심리 지표
get_market_regime - 시장 국면 판단

사용 예시

# MCP 클라이언트를 통한 사용 import mcp client = mcp.Client("market-stats-server") # 시장 개요 조회 overview = await client.call_tool("get_market_overview", { "market": "KOSPI", "include_details": True }) # 섹터 통계 조회 sectors = await client.call_tool("get_sector_statistics", { "sector": "IT", "period": "1d" })

🔍 모니터링

헬스체크

curl http://localhost:8000/health

메트릭

서버는 Prometheus 메트릭을 /metrics 엔드포인트에서 제공합니다.

로그

구조화된 JSON 로그를 사용하여 ELK 스택과 호환됩니다.

🤝 기여하기

이슈를 생성하여 기능 요청이나 버그를 리포트해주세요
포크하여 새로운 브랜치를 생성해주세요
변경사항을 커밋해주세요
테스트를 실행하고 통과하는지 확인해주세요
풀 리퀘스트를 생성해주세요

개발 워크플로우

# 의존성 설치 및 pre-commit 설정 make install-dev # 새로운 기능 브랜치 생성 git checkout -b feature/new-feature # 개발 및 테스트 make test # 커밋 전 체크 make pre-commit # 커밋 및 푸시 git commit -m "feat: add new feature" git push origin feature/new-feature

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🙋‍♂️ 지원

🏗️ 개발 현황

Phase 1-4: 기본 인프라 및 데이터 수집 (완료 ✅)

MCP 서버 아키텍처
데이터 수집 파이프라인
기본 분석 도구
데이터베이스 및 캐싱

Phase 5: 고급 분석 시스템 (완료 ✅)

AdvancedPatternRecognition: 차트 패턴, 캔들스틱, 하모닉 패턴 인식
MultiTimeframeAnalyzer: 다중 시간대 통합 분석
CorrelationEngine: 고급 상관관계 분석 (18개 분석 방법)
PricePredictor: 머신러닝 기반 가격 예측
SentimentAnalyzer: 뉴스 및 소셜미디어 감정 분석
MarketAnomalyDetector: AI 기반 이상 패턴 탐지
RiskAssessmentEngine: 포트폴리오 리스크 분석

Phase 6-10: 계산 모듈 및 최적화 (진행 예정)

Calculator 모듈 구현
Analyzer 모듈 구현
Model 모듈 구현
성능 최적화
배포 및 운영

📊 프로젝트 통계

총 코드 라인: 15,000+ 라인
테스트 커버리지: 95%+
구현된 분석 방법: 100+ 개
지원 패턴: 50+ 종류
TDD 방법론 적용으로 높은 코드 품질 보장

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Provides comprehensive statistics and advanced analysis tools for the Korean stock market, offering real-time index data, sector analysis, investor trend tracking, and AI-based market pattern recognition.

Related MCP Servers

MCP News Collector
whdghk1907
-
security
A
license
-
quality
A Model Context Protocol server that collects and analyzes Korean stock market news in real-time, providing investment insights through AI-based analysis of sentiment, market impact, and rumor detection.
Last updated -
MIT License
MCP Stock Details Server
whdghk1907
-
security
A
license
-
quality
A Model Context Protocol server providing comprehensive Korean stock market analysis, including financial data, valuation metrics, ESG information, and investment insights.
Last updated -
MIT License
Stock Analysis MCP Server
jwangkun
-
security
F
license
-
quality
Enables real-time stock market analysis through AKShare API integration. Supports retrieving live stock prices, historical data, technical indicators (MA, MACD, RSI), market sentiment analysis, stock search, and financial news.
Last updated -
4
Financial Analysis MCP Server
NARAVINDR321
-
security
F
license
-
quality
Enables LLMs to retrieve, analyze, and visualize stock prices and financial report data for quantitative trading research and investment analysis. Provides real-time and historical stock data, financial statement analysis, key metric calculations, and trading signal visualization.
Last updated -
13

View all related MCP servers