# BigKinds MCP 시작하기 - 완벽 가이드

> 5분이면 충분합니다. Claude에게 한국 뉴스를 분석하는 능력을 부여하세요.

## 이런 분들께 추천합니다

| 직업/관심사 | 활용 예시 |
|------------|----------|
| **기자/언론인** | 경쟁사 보도 분석, 트렌드 파악, 과거 기사 검색 |
| **마케터/PR** | 브랜드 모니터링, 이슈 트래킹, 경쟁사 분석 |
| **리서처/애널리스트** | 산업 트렌드 분석, 대용량 데이터 수집, 리포트 작성 |
| **투자자** | 종목 뉴스 모니터링, 섹터 트렌드 분석 |
| **학생/연구자** | 논문 자료 수집, 시계열 분석, 여론 연구 |
| **개발자** | 뉴스 API 활용, 데이터 파이프라인 구축 |

---

## 설치 전 확인사항

### 필수 요구사항
- **Python 3.12 이상** (권장: 3.12 또는 3.13)
- **Claude Desktop** (최신 버전)

Python 버전 확인:
```bash
python --version
# 또는
python3 --version
```

Python 3.12 미만이면 [python.org](https://www.python.org/downloads/)에서 최신 버전 설치

---

## 설치 (3단계, 5분 소요)

### 1단계: Claude Desktop 설치

아직 없다면 [Claude Desktop](https://claude.ai/download) 다운로드

### 2단계: uv 설치 (권장)

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
```

> **uv가 뭔가요?** Python 패키지를 설치 없이 바로 실행해주는 도구입니다. 가볍고 빠릅니다.

### 3단계: Claude Desktop 설정

#### macOS
`~/Library/Application Support/Claude/claude_desktop_config.json` 파일을 열어서:

```json
{
  "mcpServers": {
    "bigkinds": {
      "command": "uvx",
      "args": ["bigkinds-mcp"]
    }
  }
}
```

#### Windows
`%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bigkinds": {
      "command": "uvx",
      "args": ["bigkinds-mcp"]
    }
  }
}
```

> 파일이 없다면 새로 만들어주세요.

### 4단계: Claude Desktop 재시작

설정 후 Claude Desktop을 완전히 종료하고 다시 시작하세요.

---

## 첫 번째 사용 (바로 시작!)

Claude Desktop에서 이렇게 물어보세요:

```
"오늘 AI 관련 뉴스 5개만 보여줘"
```

Claude가 자동으로:
1. 오늘 날짜 확인 ✓
2. BigKinds에서 "AI" 검색 ✓
3. 최신 뉴스 5개 요약 ✓

**결과 예시:**

```markdown
2025년 12월 16일 AI 뉴스 5건

1. 삼성전자, AI 반도체 파운드리 공정 혁신
   - 매일경제 | 2025-12-16 09:15
   - 삼성전자가 AI 칩 전용 2나노 공정 개발에 성공...

2. 네이버, 하이퍼클로바X 업그레이드
   - 한국경제 | 2025-12-16 08:42
   - GPT-4 수준 성능 도달, 한국어 특화...
```

---

## 자주 쓰는 질문 모음

### 일일 업무용

```
"오늘 반도체 관련 경제지 뉴스"
"최근 일주일 핀테크 뉴스 요약"
"오늘 가장 화제인 이슈 Top 10"
```

### 트렌드 분석

```
"지난 한 달간 전기차 뉴스 추이"
"삼성전자 vs SK하이닉스 뉴스량 비교"
"2025년 AI 기사 월별 통계"
```

### 심층 조사

```
"메타버스 관련 2025년 전체 기사를 JSON으로 내보내기"
"카카오 관련 뉴스 500건 샘플링해서 분석"
```

---

## 시나리오별 활용법

### 시나리오 1: 출근길 뉴스 브리핑

**매일 아침 이렇게 물어보세요:**

```
오늘 [내 관심 분야] 관련 주요 뉴스 5개를 브리핑해줘.
경제지 위주로, 각 기사 2-3문장으로 요약.
```

**소요 시간:** 10초
**얻는 것:** 맞춤형 뉴스 브리핑

---

### 시나리오 2: 경쟁사 모니터링

**월요일 주간 회의 전:**

```
지난 일주일간 [경쟁사A], [경쟁사B], [우리 회사] 뉴스량 비교.
각 기업별 주요 이슈 Top 3도 정리해줘.
```

**소요 시간:** 30초
**얻는 것:** 경쟁 현황 리포트

---

### 시나리오 3: 투자 종목 리서치

**관심 종목 뉴스 분석:**

```
최근 3개월간 [종목명] 관련 뉴스를
월별로 집계하고, 주요 이슈를 시계열로 정리해줘.
```

**소요 시간:** 1분
**얻는 것:** 종목 뉴스 타임라인

---

### 시나리오 4: 논문/리포트 자료 수집

**대용량 데이터 필요할 때:**

```
2024-2025년 "기후변화" 관련 전체 기사를
CSV로 내보내고, Python 분석 코드도 만들어줘.
```

**소요 시간:** 5분
**얻는 것:** 수천 건 기사 + 분석 코드

---

## 고급 활용: 로그인 기능

### 연관어 분석 & 키워드 트렌드

BigKinds 무료 회원가입 → 환경변수 설정으로 추가 기능 사용

**설정 방법:**

```json
{
  "mcpServers": {
    "bigkinds": {
      "command": "uvx",
      "args": ["bigkinds-mcp"],
      "env": {
        "BIGKINDS_USER_ID": "your_email@example.com",
        "BIGKINDS_USER_PASSWORD": "your_password"
      }
    }
  }
}
```

**사용 가능한 추가 기능:**
- 키워드 트렌드 시계열 그래프
- TF-IDF 기반 연관어 분석

---

## 자주 묻는 질문 (FAQ)

### Q1. 무료인가요?
A. **100% 무료**입니다. BigKinds API를 활용하며, 별도 비용이 없습니다.

### Q2. Claude Desktop 외에도 쓸 수 있나요?
A. 네, **Claude Code, Cursor, VS Code** 등 MCP를 지원하는 모든 도구에서 사용 가능합니다.

### Q3. 검색 결과가 너무 많으면?
A. Claude가 자동으로 `smart_sample` 또는 `export_all_articles`를 제안합니다.

### Q4. 기사 전문을 볼 수 있나요?
A. 네, `get_article` 도구로 **전체 본문**을 가져올 수 있습니다.

### Q5. 언론사나 카테고리 필터링은?
A. 72개 언론사, 8개 카테고리 필터 지원. "경향신문 경제 뉴스"처럼 자연어로 요청하세요.

### Q6. 데이터를 로컬에 저장할 수 있나요?
A. `export_all_articles`로 **JSON/CSV/JSONL** 형식 저장 가능. 최대 50,000건.

---

## 문제 해결

### Claude Desktop에서 BigKinds가 안 보여요

**원인 1: 설정 파일 문제**
1. `claude_desktop_config.json` 파일 위치 확인
   - macOS: `~/Library/Application Support/Claude/`
   - Windows: `%APPDATA%\Claude\`
   - Linux: `~/.config/Claude/`
2. JSON 문법 오류 체크 (쉼표, 중괄호)
3. Claude Desktop **완전히 종료** 후 재시작 (트레이 아이콘도 종료)

**원인 2: MCP 서버 로그 확인**
- macOS/Linux: `~/Library/Logs/Claude/mcp*.log`
- Windows: `%APPDATA%\Claude\logs\mcp*.log`

로그에서 다음 에러 확인:
- "Failed to start MCP server" → uvx 설치 확인
- "Python version" → Python 3.12+ 설치 확인
- "Permission denied" → 아래 권한 문제 참조

**원인 3: 개발자 도구 확인**
- Claude Desktop에서 `Cmd+Shift+I` (macOS) 또는 `Ctrl+Shift+I` (Windows)
- Console 탭에서 MCP 관련 오류 확인

### "command not found: uvx" 에러

```bash
# uv 재설치
curl -LsSf https://astral.sh/uv/install.sh | sh

# PATH 환경변수 추가 (macOS/Linux)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # zsh
# 또는
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # bash

# 터미널 재시작 후
uvx --version
```

**Windows에서:**
```powershell
# PowerShell 재설치
irm https://astral.sh/uv/install.ps1 | iex

# 환경변수 자동 등록됨. 안 되면 PowerShell 재시작
uvx --version
```

### Python 버전 에러

```bash
# Python 버전 확인
python --version

# 3.12 미만이면 최신 버전 설치
# macOS (Homebrew)
brew install python@3.12

# Windows: python.org에서 다운로드
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3.12
```

### 권한 오류 (Permission denied)

**macOS/Linux:**
```bash
# ~/.local/bin 권한 확인
ls -la ~/.local/bin/uvx

# 실행 권한 추가
chmod +x ~/.local/bin/uvx
```

**Windows:**
- PowerShell을 **관리자 권한**으로 실행
- `uvx bigkinds-mcp` 직접 실행해보고 오류 확인
- PATH 환경변수에 uv 경로 추가

---

## 다음 단계

- 📖 [실전 활용 시나리오 보기](USE_CASES.md)
- 🎨 [실제 결과물 예시 보기](OUTPUTS.md)
- 📚 [상세 사용 예제](EXAMPLES.md)
- 🔧 [API 레퍼런스](API_REFERENCE.md)

---

## 커뮤니티

- GitHub Issues: [버그 제보 & 기능 제안](https://github.com/seolcoding/bigkinds-mcp/issues)
- Discussions: [사용법 질문 & 팁 공유](https://github.com/seolcoding/bigkinds-mcp/discussions)
