<p align="center">
  <h1 align="center">content-research-mcp</h1>
  <p align="center">
    <strong>4개의 API. 1번의 호출. 완성된 콘텐츠 리서치 보고서.</strong>
  </p>
</p>

<p align="center">
  <a href="#"><img src="https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-purple?logo=anthropic&logoColor=white" alt="MCP"></a>
  <a href="https://github.com/wjddusrb03/content-research-mcp"><img src="https://img.shields.io/github/stars/wjddusrb03/content-research-mcp?style=social" alt="GitHub Stars"></a>
</p>


---

**네이버 데이터랩 트렌드 + 블로그/뉴스 검색 + 파파고 번역 + Unsplash 이미지**를 하나의 리서치 파이프라인으로 결합한 MCP 서버입니다. 단순 API 래퍼가 아닙니다 -- 한 번의 질문으로 완성된 리서치 보고서를 생성하는 콘텐츠 크리에이터 전용 리서치 도구입니다.

## 왜 만들었나

블로그 글을 쓰거나 유튜브 대본을 준비할 때, 매번 하는 작업이 있습니다:

1. 검색 트렌드 확인해서 주제 검증
2. 인기 블로그 글 읽으면서 인기 있는 각도 파악
3. 최신 뉴스 훑어보면서 시의성 확보
4. 무료 이미지 찾기
5. 필요하면 외국어 자료 번역

탭 4개, API 4개, 최소 30분의 반복 작업. **content-research-mcp**는 이 모든 걸 한 번의 도구 호출로 끝냅니다.

## 데모: `research_topic` 실행 결과

> **나:** "인공지능 관련 블로그 글 쓸 건데 리서치 좀 해줘"

> **Claude**가 `research_topic(topic="인공지능", english_topic="artificial intelligence")`을 호출하면:

```
# Content Research Report: 인공지능

Generated: 2026-03-21 14:30

---

## 1. Search Trend Analysis

Keyword: '인공지능' | Period: 2025-09-21 ~ 2026-03-21

  2025-10:  45.2 ######################
  2025-11:  52.8 ##########################
  2025-12:  61.0 ##############################
  2026-01:  78.4 #######################################
  2026-02:  85.1 ##########################################
  2026-03:  92.3 ##############################################

  Trend: UP (+47.1)

---

## 2. Top Blog Posts

  1. **AI 활용 마케팅 전략 총정리**
     By 마케팅연구소 (20260318)
     인공지능을 활용한 콘텐츠 마케팅 전략과 실제 사례를 분석합니다...
     Link: https://blog.naver.com/...

  2. **2026년 AI 트렌드 5가지**
     By 테크블로거 (20260315)
     올해 가장 주목할 인공지능 트렌드를 정리했습니다...
     Link: https://blog.naver.com/...

  ...

---

## 3. Latest News

  1. **국내 AI 스타트업 투자 역대 최고치 경신**
     Mon, 18 Mar 2026
     올해 1분기 국내 인공지능 스타트업에 대한 투자가...
     Link: https://news.naver.com/...

  ...

---

## 4. Free Images (Unsplash)

License: Free for commercial use (credit appreciated)

  1. AI robot in modern office
     By: Alex Knight
     Preview: https://images.unsplash.com/...
     Download: https://unsplash.com/photos/.../download

  ...

---

*Report generated by content-research-mcp*
```

도구 호출 한 번이면 트렌드, 블로그, 뉴스, 이미지까지 전부 완료.

## 기능 목록

| 도구 | 설명 |
|------|------|
| `research_topic` | **핵심 기능.** 트렌드 + 블로그 + 뉴스 + 이미지를 하나의 종합 리서치 보고서로 생성 |
| `trend_keywords` | 네이버 데이터랩으로 최대 5개 키워드의 검색 트렌드 비교 |
| `search_blogs` | 네이버 블로그에서 인기 콘텐츠와 글 방향 탐색 |
| `search_news` | 네이버 최신 뉴스 기사 검색 |
| `translate_text` | 네이버 파파고로 텍스트 번역 (en/ko/ja/zh-CN 등) |
| `search_images` | Unsplash에서 무료 상업용 이미지 검색 |
| `api_status` | 어떤 API가 설정되었는지 확인 — 미설정 키는 자동으로 스킵 |

## 설치 방법

### 자동 설치 (권장)

```bash
git clone https://github.com/wjddusrb03/content-research-mcp.git
cd content-research-mcp
pip install -r requirements.txt
python setup_wizard.py
```

설치 마법사가 자동으로:
1. API 키를 대화형으로 입력받고
2. `.env` 파일을 생성하고
3. Claude Desktop 설정에 MCP 서버를 등록하고
4. 기존 설정 파일을 백업합니다

설치 후 Claude Desktop을 재시작하면 바로 사용할 수 있습니다.

### 수동 설치

직접 설정하고 싶은 경우:

**1. 의존성 설치**

```bash
git clone https://github.com/wjddusrb03/content-research-mcp.git
cd content-research-mcp
pip install -r requirements.txt
```

**2. `.env` 파일 생성**

```bash
cp .env.example .env
```

`.env` 파일을 열고 API 키를 입력합니다:

```
NAVER_CLIENT_ID=발급받은_클라이언트_ID
NAVER_CLIENT_SECRET=발급받은_클라이언트_시크릿
UNSPLASH_ACCESS_KEY=발급받은_액세스_키
```

**3. Claude Desktop 설정에 추가**

Claude Desktop 설정 파일을 엽니다:

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

`mcpServers` 항목에 다음을 추가합니다:

```json
{
  "mcpServers": {
    "content-research": {
      "command": "python",
      "args": ["/전체/경로/content-research-mcp/server.py", "--env", "/전체/경로/content-research-mcp/.env"]
    }
  }
}
```

Claude Desktop을 재시작합니다.

## API 키 발급 가이드

모든 API가 **무료**입니다. 신용카드 등록이 필요 없습니다.

### 1. 네이버 개발자 (트렌드, 블로그, 뉴스, 번역)

1. [developers.naver.com](https://developers.naver.com) 접속
2. 네이버 계정으로 로그인
3. **Application** > **애플리케이션 등록** 클릭
4. 애플리케이션 이름: 아무거나 (예: "content-research")
5. 사용 API 선택: **검색**, **데이터랩 (검색어트렌드)**, **Papago 번역**
6. 서비스 URL에 `http://localhost` 입력
7. **Client ID**와 **Client Secret** 복사

### 2. Unsplash (무료 이미지)

1. [unsplash.com/developers](https://unsplash.com/developers) 접속
2. **New Application** 클릭
3. 약관 동의 후 앱 생성
4. **Access Key** 복사

## 도구 상세 레퍼런스

### `research_topic`

핵심 도구입니다. 4개 API를 모두 호출해서 종합 리서치 보고서를 생성합니다.

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `topic` | string | *(필수)* | 리서치할 주제 (한국어) |
| `english_topic` | string | `""` | 같은 주제의 영문 (이미지 검색용). 비어있으면 `topic` 사용 |

### `trend_keywords`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `keywords` | list[str] | *(필수)* | 비교할 키워드 목록 (최대 5개) |
| `months` | int | `6` | 분석할 기간 (개월) |

### `search_blogs`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `query` | string | *(필수)* | 검색 키워드 |
| `count` | int | `5` | 결과 수 (최대 20) |

### `search_news`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `query` | string | *(필수)* | 검색 키워드 |
| `count` | int | `5` | 결과 수 (최대 20) |

### `translate_text`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `text` | string | *(필수)* | 번역할 텍스트 |
| `source` | string | `"en"` | 원본 언어 코드 |
| `target` | string | `"ko"` | 대상 언어 코드 |

지원 언어: `en`, `ko`, `ja`, `zh-CN` 등

### `search_images`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `query` | string | *(필수)* | 검색 키워드 (영어 권장) |
| `count` | int | `5` | 이미지 수 (최대 10) |

## 사용 예시

설치 후 Claude에게 자연스럽게 말하면 됩니다:

**종합 리서치 보고서:**
> "인공지능 관련 블로그 글 쓸 건데 리서치 좀 해줘"

**키워드 트렌드 비교:**
> "'ChatGPT'와 'Claude' 검색 트렌드 비교해줘"

**블로그 검색:**
> "홈트레이닝 관련 네이버 블로그 글 찾아줘"

**최신 뉴스:**
> "최신 AI 뉴스 요약해줘"

**번역:**
> "이 영어 기사 한국어로 번역해줘"

**이미지 검색:**
> "AI 관련 무료 이미지 찾아줘"

## 요구사항

- Python 3.10+
- [Claude Desktop](https://claude.ai/download) (MCP 지원)
- API 키 (모두 무료):
  - 네이버 개발자 (Client ID + Secret)
  - Unsplash (Access Key)

### 의존성 패키지

| 패키지 | 버전 | 용도 |
|--------|------|------|
| `mcp` | >= 1.0.0 | MCP SDK (FastMCP 서버 프레임워크) |
| `httpx` | >= 0.27.0 | API 호출용 HTTP 클라이언트 |
| `python-dotenv` | >= 1.0.0 | `.env` 파일에서 API 키 로드 |

## 프로젝트 구조

```
content-research-mcp/
    server.py           # 7개 도구가 정의된 MCP 서버
    setup_wizard.py     # 대화형 설치 스크립트
    core/
        naver.py        # 네이버 API 클라이언트 (블로그, 뉴스, 트렌드, 번역)
        unsplash.py     # Unsplash API 클라이언트 (이미지 검색)
    .env.example        # API 키 템플릿
    requirements.txt    # Python 의존성
    pyproject.toml      # 패키지 메타데이터
    LICENSE             # MIT 라이선스
```

## 문제 보고 & 피드백

버그를 발견하셨거나 아이디어가 있으신가요? 이슈를 남겨주세요:

- [GitHub Issues](https://github.com/wjddusrb03/content-research-mcp/issues)

버그 보고 시 아래 내용을 포함해주시면 빠른 해결에 도움이 됩니다:
- 운영체제 (Windows / macOS / Linux)
- Python 버전 (`python --version`)
- 에러 메시지 또는 예상과 다른 동작
- 재현 방법

PR(Pull Request)도 환영합니다!

## 라이선스

MIT License. 자세한 내용은 [LICENSE](LICENSE)를 참고하세요.

---

리서치보다 글쓰기에 집중하고 싶은 콘텐츠 크리에이터를 위해 만들었습니다. 30분을 아껴줬다면 스타 하나 부탁드립니다.