📈 Stock MCP Server

This is a Model Context Protocol (MCP) server that provides technical analysis and strategy-based screening for Korean and US stocks. You can perform chart analysis and stock screening using natural language in MCP-compatible clients such as Claude Desktop and Claude Code.

✨ Features

• 🇰🇷 Korean Stock Analysis — OHLCV + technical indicators for all KOSPI/KOSDAQ stocks based on pykrx

• 🇺🇸 US Stock Analysis — NYSE/NASDAQ stocks based on yfinance + market cap/PER/52-week high/low

• 🔍 Stock Search — Find stock codes by stock name (Korean stocks)

• 📊 10 Momentum Strategies + 7 Breakout Strategies — From Golden Cross to VCP

• 🎯 Two Screening Philosophies — 🐎 Catching the Running Horse vs 🌱 Finding the Horse About to Run

• 🔎 Multi-stage Pre-filters — Volume spikes, Trend Template, RS, 52-week bands, etc.

Related MCP server: KIS MCP Server

🛠️ Tools

🎯 Screening: Two Philosophies

🐎 Momentum — Catching the Running Horse

Captures Stage 2 continuation for stocks that have already entered an uptrend. Based on O'Neil's CANSLIM and Minervini's Trend Template theories.

Pipeline

시드 (네이버 거래량/상승률/급등  |  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 전략 적용

Applied Strategies (10)

• Existing 4: Golden Cross + Volume, Pullback Buy, Momentum Breakout, Volume Explosion

• New 6: RSI Divergence, MACD Divergence, Stochastic, BB Squeeze, Ichimoku Breakout, 3-line Alignment

🌱 Breakout — Finding the Horse About to Run

Captures stocks that haven't moved significantly yet, in the accumulation phase / pre-breakout. Based on Mark Minervini's VCP pattern and Wyckoff accumulation theory.

Pipeline

시드 (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)

Applied Strategies (7)

• Reused 4: Pullback Buy, Volume Explosion, MACD Divergence, BB Squeeze

• New 3: VCP Volatility Contraction, Silent Accumulation, Late Stage 1 Transition

🧪 Comparison of the Two Modes

Practical Result Comparison Example

Based on the same market (KOSPI):

• Momentum: Perspect (meets 6 strategies) — A stock already running

• Breakout: Daewon Cable 30-day -20.32%, pullback + VCP at 72% of 52-week high — Typical accumulation

📊 New Breakout Strategy Explanation

VCP (Volatility Contraction Pattern)

Divides the last 15 days into three 5-day segments to determine if the high-low range (%) sequentially contracts. Coiling spring shape → Breakout imminent. (Mark Minervini)

Silent Accumulation

Average volume of the last 20 days is higher than the previous 20 days with some spike days, but the price fluctuation range for the same 20 days is within ±8% → Hidden institutional accumulation.

Late Stage 1 Transition

Transition phase from a bottom box range (Stage 1) to a gentle rise (early Stage 2).

• MA60 slope higher than 1 month ago

• MA20 > MA60 (Short-term upward transition)

• Close > MA60 (Support secured)

• BB width ≤ 20-day average (Volatility not yet expanded)

🔎 Pre-filter Parameter Cheat Sheet

Momentum Screener Common

Breakout Screener Common

📦 Installation

Prerequisites

• Python 3.13+

• uv (Recommended)

Setup

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

🚀 Usage

Claude Desktop Integration

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Direct Execution

uv run python server.py

💬 Conversation Examples

Individual Stock Analysis

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

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

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

Screening (Running Horse)

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

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

Screening (Horse About to Run)

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

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

Individual Stock Strategy Diagnosis

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

📋 Output Examples

Momentum Screening Results (Summary)

{
  "스크리닝일": "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 Screening Results (Summary)

{
  "스크리닝일": "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 server framework

• pykrx — Korea Exchange data

• yfinance — Yahoo Finance data

• ta — Technical analysis indicators

• BeautifulSoup + lxml — Naver Finance / Yahoo Screener HTML parsing

• pandas — Data processing

📚 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 — Price-Volume Accumulation/Distribution Theory

• Stan Weinstein — Secrets for Profiting in Bull and Bear Markets (Stage Analysis)

📄 License

MIT