📈 Stock MCP Server

한국/미국 주식의 기술적 분석과 전략 기반 스크리닝을 제공하는 Model Context Protocol (MCP) 서버입니다. Claude Desktop, Claude Code 등 MCP 호환 클라이언트에서 자연어로 차트 분석·종목 스크리닝을 할 수 있습니다.

✨ Features

• 🇰🇷 한국 주식 분석 — pykrx 기반 KOSPI/KOSDAQ 전 종목 OHLCV + 기술적 지표
• 🇺🇸 미국 주식 분석 — yfinance 기반 NYSE/NASDAQ 종목 + 시가총액/PER/52주 고저가
• 🔍 종목 검색 — 종목명으로 종목코드 찾기 (한국 종목)
• 📊 10가지 Momentum 전략 + 7가지 Breakout 전략 — 골든크로스부터 VCP까지
• 🎯 두 가지 스크리닝 철학 — 🐎 달리는 말 잡아타기 vs 🌱 곧 달릴 말 찾기
• 🔎 다단 사전필터 — 거래량 급증·Trend Template·RS·52주 밴드 등

🛠️ Tools

Tool	설명	입력 예시
get_stock_analysis	한국 종목 기술적 분석	ticker="005930" (삼성전자)
get_us_stock_analysis	미국 종목 기술적 분석	symbol="NVDA"
search_stock	종목명 → 종목코드 검색	keyword="알체라"
screen_kr_momentum	🐎 한국 달리는 말 잡아타기 (Stage 2 추세)	market="ALL"
screen_us_momentum	🐎 미국 달리는 말 잡아타기	symbols=None (Yahoo 자동 시드)
screen_kr_breakout	🌱 한국 곧 달릴 말 찾기 (VCP·매집·Stage 1 말기)	market="ALL"
screen_us_breakout	🌱 미국 곧 달릴 말 찾기	symbols=None
diagnose_stock	특정 종목 전략 진단	ticker="005930", market="KR"

🎯 Screening: 두 가지 철학

🐎 Momentum — 달리는 말 잡아타기

이미 상승 추세에 진입한 종목의 추세 지속(Stage 2 continuation) 을 포착합니다. O'Neil의 CANSLIM, Minervini의 Trend Template 이론 기반.

파이프라인

시드 (네이버 거래량/상승률/급등  |  Yahoo most_actives/day_gainers/small_cap_gainers)
  ↓
① min_trade_value         — 유동성
② 당일 과열 제외 +10% 이상  — 추격매수 방지
③ 20일 내 거래량 급증 ≥ 3x  — 자금 유입 시그널
④ Minervini Trend Template — Stage 2 6조건 (ON)
⑤ 52주 고점 근접            — OFF (Trend Template과 중복)
⑥ RS vs 지수               — OFF (opt-in, 강한 종목만 보고 싶을 때)
  ↓
10가지 Momentum 전략 적용

적용 전략 (10)

• 기존 4: 골든크로스+거래량, 눌림목 매수, 모멘텀 돌파, 거래량 폭발
• 신규 6: RSI 다이버전스, MACD 다이버전스, 스토캐스틱, BB 스퀴즈, 일목균형표 돌파, 3선 정배열

🌱 Breakout — 곧 달릴 말 찾기

아직 크게 움직이지 않은 매집 단계 / 돌파 직전 종목을 포착합니다. Mark Minervini의 VCP 패턴, Wyckoff 매집 이론 기반.

파이프라인

시드 (Momentum과 동일 — 매집도 거래량에 반영됨)
  ↓
① min_trade_value
② 당일 과열 제외 +10% 이상
③ 누적 상승 한도: 최근 30일 +30% 이상 제외   ← Breakout 전용
④ 52주 밴드: 고점 × 0.85 이하 AND 저점 × 1.20 이상 ← 전용 (중간권만)
⑤ 20일 내 거래량 급증 ≥ 2x                    (momentum의 3x보다 완화)
  ↓
Breakout 7전략 적용  (Trend Template / 52w 근접 / RS 모두 off)

적용 전략 (7)

• 재사용 4: 눌림목 매수, 거래량 폭발, MACD 다이버전스, BB 스퀴즈
• 신규 3: VCP 변동성 수축, 조용한 매집, Stage 1 말기 전환

🧪 두 모드 비교

	🐎 Momentum	🌱 Breakout
철학	추세 지속	매집 → 돌파 초기
누적 상승률	제한 없음	30일 +30% 이상 제외
52주 위치	고점 근접 권장	고점 85% 이하 + 저점 120% 이상 밴드
Trend Template	ON (MA 정배열 요구)	OFF
거래량 급증	3.0x	2.0x (매집은 덜 폭발적)
전략 개수	10개	7개 (신규 3 포함)
적합한 타이밍	시장 강세기, 추세 추종	조정기 후 재진입, 바닥 반전

실전 결과 비교 예시

동일 시장(KOSPI) 기준:

• Momentum: 퍼스텍(6전략 충족) — 이미 달리고 있는 종목
• Breakout: 대원전선 30일 -20.32%, 52주고점 72% 지점에서 눌림목+VCP — 매집 전형

📊 신규 Breakout 전략 설명

VCP (Volatility Contraction Pattern)

최근 15일을 5일씩 3구간으로 나눠 각 구간의 고저 범위(%)가 순차 축소되는지 판정. 코일링 스프링 형태 → 돌파 임박. (Mark Minervini)

조용한 매집 (Silent Accumulation)

최근 20일 거래량 평균이 이전 20일 대비 증가하고 급증일도 있지만, 같은 20일 가격 변동폭은 ±8% 이내 → 시장에 드러나지 않은 세력 매집.

Stage 1 말기 전환

바닥 박스권(Stage 1)에서 완만한 상승(Stage 2 초입)으로 넘어가는 구간.

• MA60 기울기 1개월 전 대비 상승
• MA20 > MA60 (단기 상향 전환)
• 종가 > MA60 (지지 확보)
• BB폭 ≤ 20일 평균 (아직 변동성 미확장)

🔎 사전필터 파라미터 치트시트

Momentum 스크리너 공통

파라미터	기본	용도
exclude_if_up_pct	10.0	오늘 +10% 이상 제외. None이면 미적용
spike_threshold	3.0	거래량 급증 배율
enable_trend_template	True	Minervini Trend Template
enable_rs_filter	False	RS 필터 (강한 종목만 보고 싶을 때 on)
min_rs_outperformance	0.0	벤치마크 초과수익(pp) 임계값

Breakout 스크리너 공통

파라미터	기본	용도
max_cumulative_return_pct	30.0	최근 N일 누적 상승률 상한(%)
cumulative_return_days	30	누적 계산 구간
high_ceiling	0.85	52주 고점 × 이 값 이하만 통과
low_floor	1.20	52주 저점 × 이 값 이상만 통과
spike_threshold	2.0	거래량 급증 (매집은 완화된 배율)

📦 Installation

Prerequisites

• Python 3.13+
• uv (권장)

Setup

git clone https://github.com/Juuuuuuni/stock-mcp-server.git
cd stock-mcp-server
uv sync

🚀 Usage

Claude Desktop 연동

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows)에 다음을 추가:

{
  "mcpServers": {
    "stock-analyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/절대/경로/stock-mcp-server",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

직접 실행

uv run python server.py

💬 대화 예시

개별 종목 분석

👤 삼성전자 최근 분석해줘
🤖 [get_stock_analysis("005930")] → 현재가 / RSI / MACD / 추세 해석

👤 NVDA 한 달 차트 분석
🤖 [get_us_stock_analysis("NVDA", days=30)]

👤 알체라 종목코드가 뭐야?
🤖 [search_stock("알체라")] → 347860

스크리닝 (달리는 말)

👤 지금 코스피에서 뜨는 종목 찾아줘
🤖 [screen_kr_momentum(market="KOSPI")]
   → Stage 2 추세 + 거래량 급증 종목. 퍼스텍(6전략), 대우건설(3전략) …

👤 미국 주식에서 강세 종목만 (RS 10pp 이상)
🤖 [screen_us_momentum(enable_rs_filter=True, min_rs_outperformance=10.0)]

스크리닝 (곧 달릴 말)

👤 코스닥에서 매집 단계 종목 스크리닝
🤖 [screen_kr_breakout(market="KOSDAQ")]
   → 누적 상승 30% 미만 + 52주 중간권 + VCP/매집 패턴

👤 아직 안 오른 바닥 종목만 (최근 30일 +10% 이내)
🤖 [screen_kr_breakout(max_cumulative_return_pct=10.0)]

개별 종목 전략 진단

👤 알체라 지금 어떤 단계야?
🤖 [diagnose_stock(ticker="347860", market="KR")]
   → 10전략 중 어느 조건 통과했는지 상세 진단

📋 출력 예시

Momentum 스크리닝 결과 (요약)

{
  "스크리닝일": "20260413",
  "대상시장": "KOSPI",
  "시드후보수": 80,
  "필터링_단계별_통과": {
    "당일과열제외": 64,
    "거래량급증": 31,
    "Trend_Template": 8,
    "52주고점근접": 0,
    "RS": 0
  },
  "필터링결과수": 26,
  "결과": [
    {
      "종목코드": "010820",
      "종목명": "퍼스텍",
      "전략": "모멘텀 돌파",
      "점수": "5/5",
      "현재가": 2340,
      "등락률": "+4.23%",
      "RSI": 68.4,
      "거래량비": "2.1x",
      "20일내_최대거래량배율": "8.7x",
      "복수전략": true
    }
  ]
}

Breakout 스크리닝 결과 (요약)

{
  "스크리닝일": "20260413",
  "모드": "Breakout (곧 달릴 말)",
  "대상시장": "KOSPI",
  "시드후보수": 80,
  "필터링_단계별_통과": {
    "당일과열제외": 64,
    "누적상승한도": 55,
    "52주밴드": 22,
    "거래량급증": 12
  },
  "필터링결과수": 28,
  "결과": [
    {
      "종목코드": "006340",
      "종목명": "대원전선",
      "전략": "눌림목 매수",
      "점수": "5/5",
      "현재가": 1245,
      "30일누적": "-20.32%",
      "52주고점대비": "72.2%",
      "52주저점대비": "128.4%",
      "복수전략": true
    }
  ]
}

🧩 Tech Stack

• FastMCP — MCP 서버 프레임워크
• pykrx — 한국거래소 데이터
• yfinance — Yahoo Finance 데이터
• ta — 기술적 분석 지표
• BeautifulSoup + lxml — 네이버 금융 / Yahoo 스크리너 HTML 파싱
• pandas — 데이터 처리

📚 References

• William J. O'Neil — How to Make Money in Stocks (CANSLIM)
• Mark Minervini — Trade Like a Stock Market Wizard (Trend Template, VCP)
• Richard Wyckoff — 가격-거래량 매집/분산 이론
• Stan Weinstein — Secrets for Profiting in Bull and Bear Markets (Stage Analysis)

📄 License

MIT