Metadata-Version: 2.4
Name: naver-stock-mcp
Version: 0.1.0
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

# stock-mcp-server

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

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

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

---

## 목차

- [제공하는 도구](#제공하는-도구)
- [간편 설치 (원클릭 스크립트)](#간편-설치-원클릭-스크립트)
- [수동 설치 방법](#수동-설치-방법)
  - [Step 1. Python 설치](#step-1-python-설치)
  - [Step 2. 이 프로젝트 다운로드](#step-2-이-프로젝트-다운로드)
  - [Step 3. 패키지 설치](#step-3-패키지-설치)
  - [Step 4. Claude에 MCP 서버 등록](#step-4-claude에-mcp-서버-등록)
  - [Step 5. 동작 확인](#step-5-동작-확인)
- [활용 가이드](#활용-가이드)
  - [차트 분석](#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 지수 | "오늘 코스피 어때?" |

---

## 간편 설치 (원클릭 스크립트)

복잡한 설정이 어려우신 분은 아래 스크립트로 자동 설치할 수 있습니다.

### Windows

1. **Python 3.11 이상 설치** — https://www.python.org/downloads/
   (설치 시 "Add Python to PATH" 체크)
2. 이 저장소를 ZIP으로 다운로드 → 압축 해제
3. 압축 해제한 폴더에서 **`install.bat`을 더블클릭**

### macOS / Linux

1. **Python 3.11 이상 설치**
2. 이 저장소를 다운로드 또는 clone
3. 터미널에서:
   ```bash
   cd naver-stock-mcp
   chmod +x install.sh
   ./install.sh
   ```

스크립트가 자동으로:
- Python 버전 확인
- 패키지 설치 (`pip install -e .`)
- Claude Desktop 설정 파일에 MCP 서버 등록 (기존 설정 보존)

설치 완료 후 **Claude Desktop을 완전히 종료했다가 재시작**하면 됩니다.

---

## 수동 설치 방법

자동 설치 대신 직접 설치하고 싶다면 아래 단계를 따르세요.

### Step 1. Python 설치

이미 Python이 설치되어 있다면 이 단계를 건너뛰세요.

**1-1. 파이썬 다운로드**

https://www.python.org/downloads/ 에 접속해서 **Python 3.11 이상** 버전을 다운로드합니다.

**1-2. 설치 시 주의사항**

설치 화면에서 **반드시 "Add Python to PATH" 체크박스를 체크**하세요. 이걸 안 하면 터미널에서 `python` 명령어가 안 됩니다.

**1-3. 설치 확인**

터미널(명령 프롬프트)을 열고 아래 명령어를 입력합니다:

```bash
python --version
```

`Python 3.11.x` 이상이 나오면 성공입니다.

> **터미널 여는 법**
> - Windows: `Win + R` → `cmd` 입력 → 확인
> - Mac: `Cmd + Space` → `터미널` 검색 → 실행

---

### Step 2. 이 프로젝트 다운로드

**방법 A: Git이 설치되어 있는 경우**

```bash
git clone https://github.com/Johnhyeon/naver-stock-mcp.git
```

**방법 B: Git이 없는 경우**

1. 이 페이지 상단의 초록색 **"Code"** 버튼 클릭
2. **"Download ZIP"** 클릭
3. 다운로드된 ZIP 파일 압축 해제
4. 압축 해제한 폴더를 원하는 위치에 이동 (예: `C:\stock-mcp-server`)

---

### Step 3. 패키지 설치

터미널에서 다운로드한 폴더로 이동한 뒤 설치합니다:

```bash
# 폴더로 이동 (경로는 본인 환경에 맞게)
cd C:\stock-mcp-server

# 설치
pip install -e .
```

설치가 끝나면 확인:

```bash
stock-mcp-server --help
```

뭔가 출력이 나오면 성공입니다. 에러가 나면 터미널을 껐다 다시 열고 시도해보세요.

> **`pip`가 안 된다면?**
> ```bash
> python -m pip install -e .
> ```
> 이렇게 해보세요.

---

### Step 4. Claude에 MCP 서버 등록

사용하는 환경에 따라 하나만 따라하세요.

#### 방법 A: Claude Desktop (추천)

Claude Desktop 앱이 설치되어 있어야 합니다.
https://claude.ai/download 에서 다운로드할 수 있습니다.

**4-A-1. 설정 파일 열기**

- Windows: 파일 탐색기 주소창에 아래 경로를 붙여넣기하세요:
  ```
  %APPDATA%\Claude
  ```
- Mac:
  ```
  ~/Library/Application Support/Claude
  ```

**4-A-2. 설정 파일 수정**

해당 폴더에 `claude_desktop_config.json` 파일이 있으면 열고, 없으면 새로 만듭니다.

아래 내용을 입력하고 저장합니다:

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

> **이미 다른 MCP 서버가 등록되어 있다면?**
> `mcpServers` 안에 `"stock-data": { ... }` 부분만 추가하세요. 기존 것을 지우면 안 됩니다.

**4-A-3. Claude Desktop 재시작**

앱을 완전히 종료했다가 다시 실행합니다.

#### 방법 B: Claude Code (CLI)

터미널에서 한 줄만 입력하면 됩니다:

```bash
claude mcp add stock-data -- stock-mcp-server
```

---

### Step 5. 동작 확인

Claude에서 아래 질문을 해보세요:

```
삼성전자 현재가 알려줘
```

종목명, 현재가, 전일대비, 거래량 등이 나오면 **설치 완료**입니다.

안 된다면:
1. 터미널에서 `stock-mcp-server --help`가 되는지 확인
2. Claude Desktop을 완전히 종료 후 재시작
3. `claude_desktop_config.json` 파일 내용에 오타가 없는지 확인

---

## 활용 가이드

아래 질문들을 그대로 복사해서 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
