# youtube-summary-skill

A local MCP server + Claude skill that turns any YouTube URL into a **bilingual (English + Traditional Chinese) study-oriented** HTML summary — with a thumbnail, richly-written key points, a multiple-choice quiz, and the full timestamped transcript baked in. Paste a URL into Claude Desktop, get back a self-contained offline HTML file. A markdown archive of every summary is auto-saved to disk so you can grep through them later.

Built on top of [`fastmcp`](https://github.com/jlowin/fastmcp) and [`youtube-transcript-api`](https://github.com/jdepoix/youtube-transcript-api), with an optional local Whisper fallback for videos with no captions.

> **Status:** Windows-first. Tested on Windows 11 + Python 3.14 + Claude Desktop.

## What you get

Each summary is a single self-contained HTML file (~250 KB with an embedded thumbnail) containing:

- **Header** — thumbnail, real title/uploader (fetched via YouTube's public oEmbed), duration, topic, "Open on YouTube" link, and an EN / 中文 language toggle in the corner.
- **Summary** — 3–5 sentence overview of the whole talk.
- **Takeaway** — 2–3 sentence distilled answer to "if you remember one thing from this video…"
- **Key Points** — 5–8 points, each a bold lead sentence followed by a 3–5 sentence paragraph explaining the mechanism and referencing the speaker by name. A subtle `[MM:SS]` link at the end of each paragraph seeks the corresponding moment on YouTube.
- **Quiz** — 4–6 multiple-choice questions, teacher-testing-student style, with reveal-answer buttons and timestamp-cited explanations.
- **Full transcript** — timestamped, collapsed by default, expands inline for reference. Every timestamp is a link to that moment on YouTube.
- **Markdown archive** — same content saved to `~/claude_workspace/youtube-summaries/` (configurable) as a plain `.md` file with YAML frontmatter, so you can grep, sync, or feed to other tools.

All copy — summary, takeaway, key points, quiz, section headings — lives in a single JavaScript `COPY = { en, zh }` object and toggles instantly with no page reload. Only the transcript stays in its original language (that's the raw source).

## Requirements

- **Python 3.10+** on PATH.
- **[Claude Desktop](https://claude.ai/download)** — this skill uses MCP over stdio, which Claude Desktop supports natively. Claude.ai (browser) also supports local MCP servers via its connector settings.

## Install (Windows)

```powershell
git clone https://github.com/antwang0604/youtube-summary-skill.git
cd youtube-summary-skill
./install.ps1
```

That single command:

1. Creates a Python venv under `.venv/`.
2. Installs `requirements.txt` (fastmcp, youtube-transcript-api, truststore).
3. Runs a smoke test that fetches the Cynthia Breazeal TED transcript.
4. Merges an MCP entry into `%APPDATA%\Claude\claude_desktop_config.json` (preserving any existing servers).
5. Copies `SKILL.md` and `template_reference.html` to `%USERPROFILE%\.claude\skills\youtube-video-summary\`.

Flags:

```powershell
./install.ps1 -Whisper    # Also install yt-dlp + faster-whisper for captionless videos.
./install.ps1 -SkipTest   # Skip the smoke test (e.g. offline).
```

After install, **fully quit Claude Desktop from the tray icon** (closing the window keeps it running) and reopen it.

### Optional: Whisper fallback

For videos with no captions at all, the server can transcribe audio locally. Install the deps and put `ffmpeg` on PATH:

```powershell
./install.ps1 -Whisper
winget install Gyan.FFmpeg   # or: choco install ffmpeg
```

The fallback uses `faster-whisper` on CPU (int8 quantization, `base` model). Without it, captionless videos return a clear error.

## Usage

Once installed, just paste a YouTube URL into any Claude Desktop chat:

```
https://www.youtube.com/watch?v=eAnHjuTQF3M
```

Claude will:

1. Call the `get_youtube_transcript` MCP tool (transcript comes back with inline `[MM:SS]` markers roughly every 20 seconds).
2. Emit a single self-contained HTML artifact following the structure in `template_reference.html`.
3. Call the `save_summary_markdown` MCP tool to persist a markdown copy to `~/claude_workspace/youtube-summaries/`.

Supported URL shapes:

- `https://www.youtube.com/watch?v=...`
- `https://youtu.be/...`
- `https://www.youtube.com/shorts/...`
- `https://www.youtube.com/embed/...`
- `https://www.youtube.com/live/...`

## Configuration

**Change the save directory.** The markdown archive defaults to `~/claude_workspace/youtube-summaries/`. To point elsewhere, set `YOUTUBE_SUMMARY_DIR` in the MCP entry inside `claude_desktop_config.json`:

```json
"youtube-summary": {
  "command": "…\\.venv\\Scripts\\python.exe",
  "args": ["…\\server.py"],
  "env": { "YOUTUBE_SUMMARY_DIR": "D:\\notes\\video-summaries" }
}
```

**Skill instructions.** All content-shape rules (how many key points, how the quiz is styled, bilingual requirements, timestamp handling) live in `SKILL.md`. Edit that file and Claude Desktop will pick up the changes on next chat.

**HTML template.** `template_reference.html` is the canonical structure Claude follows. Change design tokens (colors, fonts) or add fields there.

## Manual install (no PowerShell script)

If `install.ps1` errors out or you want to see every step:

```bash
cd youtube-summary-skill
python -m venv .venv
.venv\Scripts\activate           # Windows
# source .venv/bin/activate       # macOS/Linux
pip install -r requirements.txt
python test_server.py             # smoke test
```

Then hand-edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youtube-summary": {
      "command": "C:\\path\\to\\youtube-summary-skill\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\youtube-summary-skill\\server.py"]
    }
  }
}
```

And copy the skill into place:

```powershell
$dest = "$env:USERPROFILE\.claude\skills\youtube-video-summary"
New-Item -ItemType Directory -Force -Path $dest
Copy-Item SKILL.md, template_reference.html $dest
```

## How it works

```
┌────────────────┐   paste URL     ┌────────────────┐
│ Claude Desktop │ ──────────────> │ your prompt    │
└────────────────┘                 └────────┬───────┘
        ▲                                   │  matches SKILL.md
        │                                   │  activation rule
        │                                   ▼
        │                          ┌────────────────┐
        │  transcript + saved      │ Claude decides │
        │  markdown path returned  │ to call MCP    │
        │                          └────────┬───────┘
        │                                   │
        │                                   ▼
        │                          ┌────────────────┐
        └──────────────────────────│  server.py     │
                                   │  (fastmcp)     │
                                   │                │
                                   │ get_youtube_   │
                                   │  transcript()  │
                                   │ save_summary_  │
                                   │  markdown()    │
                                   └────────┬───────┘
                                            │
                                            ▼
                                   ┌────────────────┐
                                   │ youtube-       │
                                   │ transcript-api │
                                   │  (or Whisper)  │
                                   └────────────────┘
```

The MCP server is **spawned on demand** by Claude Desktop — you never run `python server.py` yourself. Config in `claude_desktop_config.json` tells Claude how to launch it.

## Repo layout

| File | Purpose |
|---|---|
| `server.py` | FastMCP server — two tools: `get_youtube_transcript`, `save_summary_markdown`. |
| `requirements.txt` | Core Python deps (Whisper fallback deps commented out). |
| `test_server.py` | Direct smoke test of the transcript fetcher, no MCP involved. |
| `SKILL.md` | Instructions the Claude client loads when a YouTube URL appears. |
| `template_reference.html` | Canonical HTML structure Claude produces. |
| `install.ps1` | One-shot Windows installer (venv, deps, config merge, skill copy). |
| `LICENSE` | MIT. |

## Troubleshooting

- **`ERROR: Transcripts are disabled …`** — the uploader turned captions off. Enable the Whisper fallback (`./install.ps1 -Whisper` + ffmpeg) to handle these.
- **`ERROR: No transcript available in any language …`** — YouTube has no captions at all for this video. Same fix.
- **`Whisper fallback is unavailable …`** — install `yt-dlp` and `faster-whisper`, and make sure `ffmpeg` is on PATH.
- **`ERROR: Failed to list transcripts …`** — usually a network issue, IP block from YouTube, or a stale `youtube-transcript-api`. Try `pip install -U youtube-transcript-api`.
- **`CERTIFICATE_VERIFY_FAILED`** — corporate CA / TLS-inspecting proxy. The `truststore` dep should handle this automatically; if it doesn't, check that `truststore` is installed in your venv.
- **Claude doesn't call the tool** — confirm `youtube-summary` shows up in Claude Desktop's MCP indicator with 2 tools. If it says 0 tools or red, check `%APPDATA%\Claude\logs\` for spawn errors.
- **Skill doesn't fire on a URL** — confirm `SKILL.md` is at `%USERPROFILE%\.claude\skills\youtube-video-summary\SKILL.md` and matches one of the URL shapes in the "When to activate" list.

## Contributing

Bug reports and feature requests welcome — open an issue. Small PRs (typo fixes, additional URL patterns, translations of `SKILL.md` prompt language) are the easiest to review.

Design changes to the HTML template or SKILL.md content-shape are best discussed in an issue first, since they change what every future summary looks like.

## License

MIT — see [LICENSE](LICENSE).

## Credits

- Inspired by [kar2phi/video-lens](https://github.com/kar2phi/video-lens), which tackles the same problem with a different architecture (coding-agent skill + local HTTP server + gallery).
- Uses [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api), [fastmcp](https://github.com/jlowin/fastmcp), and optionally [faster-whisper](https://github.com/SYSTRAN/faster-whisper).