📈 korea-stock-mcp

한국 주식을 위한 보수적·데이터 정직 원격 MCP 서버 Conservative, data-honest Korean equity analysis for Claude, Cursor and any MCP client

DART 전자공시의 실측 재무제표와 KRX 시세만으로 한국 상장사를 분석한다. 데이터가 없으면 없다고 답하고, 목표 주가 대신 가정이 명시된 범위를 제시하며, 매수·매도 권고를 하지 않는다.

✨ Features

• 날조 제로 — 모든 수치는 DART 공시·KRX 시세 실측치. 결측은 null + 사유로 명시, 기본값 주입 없음

• 실측 재무제표 — 사업보고서 기반 매출·영업이익·현금흐름 3~10개년, 연결(CFS) 우선/별도(OFS) 폴백 표시

• 보수적 밸류에이션 — 단일 적정가 대신 3시나리오(비관/중립/낙관) 범위, 성장률·멀티플 가정 전부 응답에 포함

• 리스크 우선 — 재무 적신호 6종 자동 검사 + 공시 위험 키워드 하이라이트, 검사 불가 항목도 구분 보고

• 교차 검증 — 시가총액 정합성 검사(주가×주식수 vs 보고 시총) 등 데이터 정합성 검증 내장

• 운영 기본기 — 글로벌 레이트 리밋, DART 쿼터 보호 캐싱, KRX IP 차단 방지 직렬화, 구조화 에러 메시지

Related MCP server: RagAlgo MCP Server

🏗️ Architecture

graph LR
    C1[Claude / claude.ai] -->|Streamable HTTP| S
    C2[Claude Desktop / Cursor] -->|Streamable HTTP| S
    subgraph Railway
        S[FastMCP 3 · stateless] --> T[tools/ 등록 계층]
        T --> A[analysis/ 순수 계산<br>ratios · valuation · risk]
        T --> SV[services/ 데이터 클라이언트]
        SV --> CA[(TTL cache)]
    end
    SV -->|재무제표 · 공시| DART[DART OpenAPI]
    SV -->|시세 · 상장목록| KRX[KRX via FinanceDataReader]

계층 원칙: tools/는 등록만(얇게) → services/는 외부 API + 캐싱 → analysis/는 순수함수(가장 두꺼운 테스트). LLM도 서버도 수치를 "암산"하지 않는다 — 모든 계산은 결정론적 함수다.

🚀 Quickstart

배포된 서버 URL 하나면 된다. API 키 불필요(공개 데이터만 제공).

claude.ai — 설정 → 커넥터 → 커스텀 커넥터 추가:

https://korea-stock-analyzer-mcp-production.up.railway.app/mcp

Claude Code:

claude mcp add --transport http korea-stock https://korea-stock-analyzer-mcp-production.up.railway.app/mcp

{
  "mcpServers": {
    "korea-stock": {
      "type": "http",
      "url": "https://korea-stock-analyzer-mcp-production.up.railway.app/mcp"
    }
  }
}

연결 후 이렇게 물어보면 된다:

"삼성전자 최근 5년 재무제표 흐름이랑 리스크 요인 짚어줘"

🛠️ Tools

모든 응답에 데이터 기준일(as_of)과 출처(data_source)가 붙는다.

☁️ Deploy Your Own

Railway 기준 (Dockerfile 자동 감지):

1. 이 레포를 포크 → Railway에서 GitHub 레포 연결

2. 환경변수:

악성 사용자 차단은 별도 환경변수 없이 자동 적용된다. Railway 요청을 자동으로 인식해 IP별 분당 30회, 반복 초과 3회 시 1시간 차단하며, /health도 분당 120회로 제한해 우회 경로를 막는다.

3. Serverless(App Sleeping) 비활성 권장 — 콜드 스타트 시 커넥터 연결 실패 방지

로컬 실행:

uv sync
DART_API_KEY=<key> uv run uvicorn app.main:app --app-dir src --port 8000

테스트:

uv run pytest                          # 단위·경계 테스트 (외부 API 없음)
uv run pytest -m live -o addopts=""    # 실제 KRX/DART 검증 (키 필요)

📊 데이터 출처와 한계

🔒 Disclaimer

본 서버의 출력은 공시·시세 데이터의 산술 가공 결과이며 투자 자문이 아니다. 시나리오 값은 명시된 가정의 계산 결과일 뿐 목표 주가가 아니다. 서버는 매수·매도·비중 판단을 제공하지 않으며, 투자 판단과 책임은 전적으로 이용자에게 있다.

🤝 Contributing

이슈·PR 환영. 원칙 하나만 지켜달라: 데이터가 없으면 없다고 답한다. 추정치 주입·하드코딩 폴백이 들어간 PR은 받지 않는다. 테스트는 uv run pytest 통과 필수.

📜 License

Apache-2.0