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 and 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 — 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)

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:

./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:

./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:

"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:

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:

{
  "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:

$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.

Credits

• Inspired by kar2phi/video-lens, which tackles the same problem with a different architecture (coding-agent skill + local HTTP server + gallery).
• Uses youtube-transcript-api, fastmcp, and optionally faster-whisper.