# instagram-analyzer MCP

공개 인스타그램 게시물 URL을 받아 **캡션(텍스트) + 사진(들)** 을 반환하는 로컬 MCP 서버입니다.

### 영상 분석 (자동 통합)

릴스/TV 영상 게시물은 **고급 영상 분석** ([watch@claude-watch](https://github.com/taoufik123-collab/claude-watch)) 을 자동 사용합니다:
- **장면 전환점** 기반 프레임 추출 (토큰 효율)
- **훅 분석** (처음 10초 밀집 샘플링)
- **구조화 보고서** (TL;DR, 주요 순간, 인용구)

첫 실행 시 watch가 없으면 자동 설치를 시도합니다.

### 사진 분석

사진/캐러셀: 캡션 + 메타데이터 + 각 이미지
- 사진·프레임을 MCP 이미지 콘텐츠로 돌려주므로, Claude 같은 멀티모달 모델이 **직접 보고 시각 분석**할 수 있습니다.
- 별도의 유료 비전 API가 필요 없습니다.

## 도구

| 도구 | 설명 |
|---|---|
| `analyze_instagram_post(url, max_images=5, num_frames=8, transcribe=True)` | **사진/캐러셀**: 캡션·메타(게시자·좋아요·댓글 수·슬라이드 수)와 각 사진 반환. **릴스/TV**: 캡션·메타 + watch@claude-watch 고급 분석(장면 기반 프레임 + 훅 분석 + 구조화 보고서) 반환. |

### 주의

- **영상 분석**: `ffmpeg`, `ffprobe`, `python3` 필수. watch는 첫 실행 시 자동 설치.
- **음성 자막**: `GROQ_API_KEY` 가 env 또는 `~/.config/watch/.env` 에 있어야 생성됩니다 (없으면 프레임 분석만).
- **인스타 인증**: 본인 계정 세션이 필수입니다 (익명 접근 불가).

## 요구사항

- Python ≥ 3.10, [`uv`](https://docs.astral.sh/uv/), `git`
- 의존성: [`mcp`](https://github.com/modelcontextprotocol/python-sdk) (v1), [`instaloader`](https://instaloader.github.io/)
- 영상 분석 (자동 설치): `ffmpeg`, `ffprobe`

## 설치

```bash
git clone https://github.com/SsangG77/instagram-analyzer-mcp.git
cd instagram-analyzer-mcp
uv sync
```

### MCP 등록 (Claude Code)

```bash
claude mcp add --scope user instagram-analyzer -- \
  uv --directory "$(pwd)" run server.py
```

## 인증 (필수)

> ⚠️ **익명(비로그인) 접근은 인스타그램이 403 / rate-limit 으로 차단합니다.** 본인 계정 세션이 필요합니다.

```bash
# 1) instaloader 로 세션 파일 생성 (대화형 로그인 — 비밀번호/2FA 입력)
instaloader --login <your_instagram_username>
```

그런 다음 MCP 환경변수를 설정합니다.

| 환경변수 | 설명 |
|---|---|
| `IG_USERNAME` | 인스타 계정명. 지정하면 instaloader 기본 경로의 세션(`session-<username>`)을 자동 로드. |
| `IG_SESSIONFILE` | (선택) 세션 파일 경로를 직접 지정. |
| `IG_PASSWORD` | (대안) 비밀번호 직접 로그인 — 챌린지에 약하므로 세션 파일 권장. |
| `GROQ_API_KEY` | (선택) Groq API 키. 영상 음성 자막 생성에 사용. 없으면 기본 자막 또는 건너뜀. |

## 영상 분석 (watch 통합)

릴스/TV 분석 시 **watch@claude-watch** 를 자동으로 사용합니다.

### 첫 실행 시 자동 설치

watch가 설치되지 않았다면, 첫 영상 분석 요청 시 자동으로:
1. GitHub에서 코드 클론 (`~/.instagram_analyzer_watch/`)
2. 필요한 Python 의존성 설치
3. 이후 요청부터 캐시된 경로 사용

### 수동 설치 (선택)

자동 설치가 실패했거나 특정 위치에 설치하고 싶다면:

```bash
git clone https://github.com/taoufik123-collab/claude-watch.git ~/.instagram_analyzer_watch
cd ~/.instagram_analyzer_watch
pip install -r requirements.txt  # 또는 uv sync
```

### 설정

`watch` 동작 커스터마이징이 필요하면 MCP 환경변수로 지정:

| 환경변수 | 설명 |
|---|---|
| `WATCH_SCRIPT_PATH` | (선택) watch.py 절대 경로 명시. 지정하지 않으면 자동 탐색 + 캐시. |
| `GROQ_API_KEY` | (선택) Groq Whisper API 키. 음성 자막 활성화. |

예) 세션 생성 후 계정명만 지정해 재등록:

```bash
claude mcp remove --scope user instagram-analyzer
claude mcp add --scope user instagram-analyzer -e IG_USERNAME=<your_username> -- \
  uv --directory "$(pwd)" run server.py
```

## 비용 / 한계 (trade-off)

- **무료** — 로컬 실행, 외부 유료 API 0.
- 단, **본인 인스타 로그인 세션이 필요**하고, 인스타의 anti-bot 로 **rate-limit / 계정 차단** 가능.
- 인스타 스크래핑은 **ToS 회색지대**이며, 인스타 내부 변경 시 깨질 수 있습니다(유지보수 부담).
- 안정성·무유지보수가 중요하면 [Apify Instagram Scraper](https://apify.com/apify/instagram-scraper) 같은 유료 스크래핑 서비스가 대안입니다.

## 라이선스

MIT