# youtube-signal-mcp

유튜브 영상의 자막과 채널 최신 영상 목록을 AI 에이전트(Claude Code, Codex, Cursor 등)가
도구로 꺼내 쓰게 해 주는 MCP 서버입니다. CLI로도 쓸 수 있습니다.

- API 키, 로그인, 영상 다운로드가 전부 없습니다. 유튜브가 공개로 주는 자막·RSS·oembed만 씁니다.
- 요약은 이 서버가 하지 않고, 서버가 자막을 넘기면 에이전트(모델)가 합니다. 그래서 키가 필요 없습니다.
- 채널을 등록해 두면 "지난번 이후 새로 올라온 영상"만 자막과 함께 돌려줍니다. 산업 동향 카드나
  주간 브리프를 만들 때 이 기능을 씁니다.

## 설치 (Claude Code 기준, 3단계)

1. `uv`가 없으면 설치합니다. https://docs.astral.sh/uv/getting-started/installation/
2. 터미널에서 한 줄:

   ```bash
   claude mcp add youtube-signal -e YT_LANGS=ko,en -- uvx --from git+https://github.com/alibabagini-cyber/youtube-signal-mcp youtube-signal-mcp
   ```

3. Claude Code를 다시 열고 이렇게 물어봅니다.

   ```
   https://www.youtube.com/watch?v=XXXXXXXXXXX 이 영상 요약해줘
   @TechTechPotato 채널 최근 영상 5개 한 줄씩 정리해줘
   ```

`claude mcp list`에 `youtube-signal`이 보이면 연결된 것입니다.

다른 클라이언트(Codex, Cursor, Claude Desktop)는 `examples/mcp-config.json`을 그 프로그램의
MCP 설정 파일에 붙여 넣으면 됩니다. 형식은 전부 같습니다.

## 에이전트가 쓰는 도구

| 도구 | 하는 일 | 입력 |
|---|---|---|
| `get_transcript` | 영상 자막을 글로 | URL 또는 11자 영상 ID, 언어 우선순위(`ko,en`), 타임스탬프 여부, 글자 수 상한 |
| `get_video_info` | 제목·채널명·썸네일 | URL 또는 ID |
| `list_channel_videos` | 채널 최신 영상 약 15개 | `@핸들`, `UC…` 채널 ID, 채널 URL |
| `watch_channels` | 지난 호출 이후 새 영상만 + 자막 | 채널 목록(비우면 channels.json) |

프롬프트(에이전트에게 시킬 일의 틀)도 세 개 들어 있습니다. Claude Code에서는 `/youtube-signal:`로 시작하는
슬래시 명령으로 뜹니다.

| 프롬프트 | 결과물 |
|---|---|
| `summarize_video` | 한 줄 결론, 순서대로 요약, 챕터 목록, 숫자·고유명사와 나온 시각 |
| `industry_signals` | 산업 신호 카드 3~7개. 신호 한 문장, 나온 시각, 사실/주장/추측 구분, 왜 중요한지 |
| `channel_digest` | 채널 최신 5편을 한 줄씩, 그리고 공통 흐름 |

`industry_signals`는 기본이 반도체/메모리 쪽으로 잡혀 있는데, `industry` 인자로 바꾸면 됩니다.

## CLI로 쓰기

```bash
uvx --from git+https://github.com/alibabagini-cyber/youtube-signal-mcp youtube-signal transcript "https://youtu.be/XXXXXXXXXXX" -l ko,en -t
uvx --from git+https://github.com/alibabagini-cyber/youtube-signal-mcp youtube-signal channel @Asianometry -n 5
uvx --from git+https://github.com/alibabagini-cyber/youtube-signal-mcp youtube-signal watch @Asianometry @TechTechPotato --max-new 2
```

자주 쓰면 `uv tool install git+https://github.com/alibabagini-cyber/youtube-signal-mcp` 한 번 하고
`youtube-signal …`로 부르면 됩니다.

## 채널 감시 세팅

1. `~/.youtube-signal-mcp/channels.json`을 만듭니다. 예시는 `examples/channels.example.json`.
   ```json
   [
     {"channel": "@Asianometry", "languages": ["en"]},
     {"channel": "@softdragon", "languages": ["ko", "en"]}
   ]
   ```
2. `youtube-signal watch`를 돌리면 새 영상만 나옵니다. 본 영상 ID는 같은 폴더 `seen.json`에 쌓입니다.
3. 채널을 처음 넣은 날은 최신 `--max-new`개(기본 2)만 가져오고 나머지 과거분은 "본 것"으로 표시합니다.
   과거 영상까지 전부 긁어오는 도구가 아닙니다.
4. cron 예: 매일 아침 8시
   ```
   0 8 * * * youtube-signal watch > ~/yt_new_$(date +\%F).json
   ```

## 환경변수

| 이름 | 뜻 | 기본 |
|---|---|---|
| `YT_LANGS` | 자막 언어 우선순위 | `en` |
| `YT_STATE_DIR` | channels.json, seen.json 위치 | `~/.youtube-signal-mcp` |
| `YT_PROXY_URL` | 자막 요청에 쓸 프록시(https://user:pass@host:port) | 없음 |

## 꼭 알아두기

- 자막이 없는 영상은 못 읽습니다. 자동 생성 자막은 오타가 있으니 숫자는 영상에서 한 번 확인하세요.
- 클라우드 서버나 VPN에서 돌리면 유튜브가 자막 요청을 막는 경우가 있습니다. 집·사무실 PC에서는
  거의 문제 없고, 막히면 `YT_PROXY_URL`을 씁니다.
- 한국어 영상은 `YT_LANGS=ko,en`으로 두세요. 기본값 `en`이면 영어 자막을 먼저 찾고, 없으면 있는 언어 아무거나 가져옵니다.
- 유튜브가 가끔 404·500을 잠깐 냅니다. 3번까지 자동으로 다시 시도합니다.

## 개발자용

```bash
git clone https://github.com/alibabagini-cyber/youtube-signal-mcp
cd youtube-signal-mcp
uv run youtube-signal channel @Asianometry -n 3
uv run youtube-signal-mcp   # stdio MCP 서버
```

`youtube_signal_mcp/core.py`가 전부이고 `server.py`(MCP)와 `cli.py`는 그걸 감싼 겉면입니다.
의존성은 `mcp`, `youtube-transcript-api` 둘뿐입니다.

MIT