Metadata-Version: 2.4
Name: naver-stock-mcp
Version: 0.1.1
Summary: 네이버 증권 데이터를 Claude에서 바로 조회할 수 있는 MCP 서버 - 한국 주식 차트, 수급, 재무지표를 자연어로 분석
Project-URL: Homepage, https://github.com/Johnhyeon/naver-stock-mcp
Project-URL: Repository, https://github.com/Johnhyeon/naver-stock-mcp
Project-URL: Issues, https://github.com/Johnhyeon/naver-stock-mcp/issues
Author: Johnhyeon
License: MIT
License-File: LICENSE
Keywords: ai,claude,finance,investment,korea,mcp,naver,stock
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Korean
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp[cli]>=1.12.0
Requires-Dist: pandas>=2.2.0
Description-Content-Type: text/markdown

# naver-stock-mcp

네이버 증권 데이터를 Claude에서 바로 조회할 수 있는 MCP 서버입니다.

API 키 없이, 설치만 하면 Claude에서 자연어로 한국 주식 데이터를 분석할 수 있습니다.

[![PyPI version](https://img.shields.io/pypi/v/naver-stock-mcp.svg)](https://pypi.org/project/naver-stock-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **왜 필요한가요?**
> AI에게 차트 이미지를 보여주면 그럴듯하게 분석하지만, 실제 숫자와 다를 수 있습니다 (할루시네이션).
> 이 MCP 서버를 설치하면 Claude가 **실제 시세 데이터**를 직접 가져와서 분석하기 때문에 정확합니다.

---

## 목차

- [제공하는 도구](#제공하는-도구)
- [빠른 시작](#빠른-시작)
- [업데이트](#업데이트)
- [수동 설치](#수동-설치)
- [활용 가이드](#활용-가이드)
  - [차트 분석](#1-차트-분석)
  - [수급 분석](#2-수급-분석)
  - [재무 / 밸류에이션](#3-재무--밸류에이션)
  - [종목 비교](#4-종목-비교)
  - [종합 리포트](#5-종합-리포트)
  - [시장 + 종목 연계](#6-시장--종목-연계)
  - [교육 / 학습용](#7-교육--학습용)
  - [매매 타이밍](#8-매매-타이밍)
- [프롬프트 잘 쓰는 팁](#프롬프트-잘-쓰는-팁)
- [FAQ](#faq)

---

## 제공하는 도구

| 도구 | 설명 | 예시 질문 |
|------|------|-----------|
| `search` | 종목명/코드로 검색 | "삼성전자 종목코드 알려줘" |
| `get_chart` | 일봉/주봉/월봉 OHLCV | "SK하이닉스 3개월 일봉 보여줘" |
| `get_price` | 실시간 현재가 | "현대차 지금 얼마야?" |
| `get_flow` | 외국인/기관/개인 순매수 | "카카오 20일 수급 분석해줘" |
| `get_financial` | PER, PBR, 시가총액 등 | "네이버 재무지표 보여줘" |
| `get_index` | KOSPI/KOSDAQ 지수 | "오늘 코스피 어때?" |

---

## 빠른 시작

### 사전 준비

| 항목 | 다운로드 링크 |
|------|--------------|
| **Python 3.11+** | https://www.python.org/downloads/ (설치 시 "Add Python to PATH" 체크 필수) |
| **Claude Desktop** | https://claude.ai/download |

### 설치 (2가지 방법 중 선택)

#### 방법 1: 원클릭 스크립트 (비개발자 추천)

1. 이 저장소에서 **`install.bat`** (Windows) 또는 **`install.sh`** (Mac/Linux) 파일만 다운로드
2. 더블클릭 또는 터미널에서 실행

> **파일만 받는 법**: 파일명 클릭 → 우측 상단 **Raw** 버튼 우클릭 → "다른 이름으로 링크 저장"

#### 방법 2: pip로 직접 설치 (개발자 추천)

```bash
pip install naver-stock-mcp
stock-mcp-setup
```

두 줄이면 끝납니다. `pip install`로 패키지 설치 후, `stock-mcp-setup`이 Claude Desktop 설정을 자동으로 등록합니다.

### 설치 완료 후

**Claude Desktop을 완전히 종료한 뒤 다시 실행**하세요.
(창 닫기가 아니라 완전 종료 — Windows는 트레이 우클릭 → Quit, Mac은 Cmd+Q)

### 동작 확인

Claude에서 다음과 같이 물어보세요:
```
삼성전자 현재가 알려줘
```

종목명, 현재가, 전일대비가 나오면 설치 완료입니다.

---

## 업데이트

새 버전이 나오면 간단하게 업데이트할 수 있습니다.

```bash
pip install --upgrade naver-stock-mcp
```

또는 `update.bat` (Windows) / `update.sh` (Mac/Linux)을 실행하세요.

업데이트 후 Claude Desktop을 재시작하면 반영됩니다.

---

## 수동 설치

Claude Desktop 설정 파일을 직접 편집하고 싶다면:

### 1. 패키지 설치
```bash
pip install naver-stock-mcp
```

### 2. 설정 파일 편집

**경로**:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**내용**:
```json
{
  "mcpServers": {
    "stock-data": {
      "command": "stock-mcp-server"
    }
  }
}
```

> 이미 다른 MCP 서버가 등록되어 있다면 `mcpServers` 안에 `"stock-data"` 항목만 추가하세요.

### 3. Claude Desktop 재시작

### Claude Code (CLI) 사용 시
```bash
claude mcp add stock-data -- stock-mcp-server
```

---

## 활용 가이드

아래 질문들을 그대로 복사해서 Claude에 붙여넣으면 됩니다.

### 1. 차트 분석

```
삼성전자 60일 일봉 보고 현재 추세 판단해줘
```

```
SK하이닉스 주봉 데이터 보고 지지선이랑 저항선 찾아줘
```

```
카카오 일봉 보고 이동평균선(5, 20, 60, 120일) 계산해서
정배열인지 역배열인지 알려줘
```

```
현대차 3개월 차트 보고 볼린저밴드 계산해서
지금 과매수인지 과매도인지 판단해줘
```

```
네이버 일봉 보고 RSI 14일 계산해줘.
과매도 구간 진입했으면 알려줘
```

---

### 2. 수급 분석

```
삼성전자 20일 수급 보고 외국인이 추세적으로 사는 건지 판단해줘
```

```
SK하이닉스 수급에서 기관이랑 외국인이 동시에 순매수한 날 찾아줘
```

```
카카오 수급 보고 개인이 팔고 외국인이 사는 구간이 있는지 확인해줘
```

```
현대차 수급 추이를 주가 흐름이랑 같이 분석해서
수급이 주가에 선행하는지 봐줘
```

---

### 3. 재무 / 밸류에이션

```
삼성전자 재무지표 보고 현재 주가가
저평가 구간인지 고평가 구간인지 판단해줘
```

```
카카오 PER이랑 PBR 보고 동종업계 대비 어떤 수준인지 의견 줘
```

```
SK하이닉스 시가총액이랑 재무지표 보고
반도체 사이클 고려해서 적정가치 의견 줘
```

---

### 4. 종목 비교

```
삼성전자랑 SK하이닉스 3개월 차트 비교해서
어디가 상대적으로 강한지 분석해줘
```

```
카카오랑 네이버 차트 + 수급 + 재무 전부 비교해서 표로 정리해줘
```

```
현대차랑 기아 최근 수급 비교해서
외국인이 어디를 더 선호하는지 알려줘
```

---

### 5. 종합 리포트

```
삼성전자 차트 + 수급 + 재무 전부 조회해서
증권사 애널리스트처럼 종합 리포트 작성해줘.
매수/매도/관망 중 하나로 결론 내줘
```

```
SK하이닉스를 아래 항목으로 분석해줘:
1. 추세 (이동평균선 기반)
2. 모멘텀 (RSI, 거래량 변화)
3. 수급 (외국인/기관 방향성)
4. 밸류에이션 (PER/PBR)
5. 종합 의견
```

---

### 6. 시장 + 종목 연계

```
코스피 지수 확인하고, 삼성전자 차트랑 비교해서
시장 대비 강한지 약한지 알려줘
```

```
코스피 지수 보고 오늘 시장 분위기 알려주고,
삼성전자 수급까지 같이 봐서 단기 방향 의견 줘
```

---

### 7. 교육 / 학습용

```
삼성전자 60일 일봉 데이터 보고
캔들 패턴(망치형, 도지, 장악형 등) 있는지 찾아서 설명해줘
```

```
SK하이닉스 차트로 엘리어트 파동 카운팅 해볼 수 있어?
현재 몇 파동인지 의견 줘
```

```
카카오 차트에서 다이버전스 발생했는지
RSI랑 주가 흐름 비교해서 확인해줘
```

```
현대차 차트 보고 와이코프 방법론으로
현재 어떤 Phase인지 분석해줘
```

---

### 8. 매매 타이밍

```
삼성전자 차트 + 수급 + 거래량 보고
지금 매수 진입하기 좋은 타이밍인지 판단해줘.
근거도 같이 알려줘
```

```
SK하이닉스 눌림목 매수 관점에서
20일선 지지 여부랑 거래량 위축 확인해줘
```

```
카카오가 바닥 다지는 중인지
차트 패턴이랑 수급으로 판단해줘
```

---

## 프롬프트 잘 쓰는 팁

AI에게 주식을 물어볼 때, **어떻게 질문하느냐**에 따라 답변 품질이 완전히 달라집니다.

### 나쁜 질문

```
삼성전자 어때?
```

→ 뭘 봐야 하는지 모호해서 AI가 두루뭉술하게 답변합니다.

### 좋은 질문

```
삼성전자 60일 일봉 보고 20일 이동평균선 기준으로
추세 판단하고, 수급도 같이 봐서 매수 관점 의견 줘
```

→ **데이터 범위** + **분석 기준** + **원하는 결론**이 명확해서 구체적인 답변이 나옵니다.

### 좋은 질문의 3요소

| 요소 | 설명 | 예시 |
|------|------|------|
| **데이터 범위** | 어떤 데이터를, 얼마나 볼지 | "60일 일봉", "20일 수급" |
| **분석 기준** | 무슨 방법으로 분석할지 | "이동평균선 기준", "RSI로", "PER 기준" |
| **원하는 결론** | 어떤 형태의 답변을 원하는지 | "매수/매도 판단", "표로 정리", "리포트 작성" |

---

## FAQ

### Q. API 키가 필요한가요?

아닙니다. 네이버 증권 공개 데이터를 사용하므로 API 키, 증권 계좌 모두 필요 없습니다.

### Q. Claude 웹(claude.ai)에서도 되나요?

로컬 MCP 서버는 **Claude Desktop(앱)** 또는 **Claude Code(CLI)**에서만 동작합니다. 웹 브라우저에서는 사용할 수 없습니다.

### Q. ChatGPT나 Gemini에서도 되나요?

이 MCP 서버는 Claude 전용입니다. 다만 MCP를 지원하는 다른 도구(Cursor, Windsurf 등)에서도 사용할 수 있습니다.

### Q. 주말에도 데이터가 나오나요?

네. 과거 차트 데이터와 재무지표는 항상 조회 가능합니다. 현재가는 장 마감 후에는 마지막 거래 시점의 가격이 나옵니다.

### Q. 무료인가요?

이 MCP 서버 자체는 무료입니다. 다만 Claude Desktop 또는 Claude Code 사용을 위한 Anthropic 구독은 별도입니다.

---

## 라이선스

MIT
