YouTube Knowledge MCP

A Model Context Protocol (MCP) server that gives AI assistants the ability to search, analyze, and extract knowledge from YouTube videos. Works with Claude Desktop, Claude Code, Claude.ai, Cursor and any MCP-compatible client.

Supports both local (stdio) and remote (Streamable HTTP) transports.

Features

Find and read

• Search videos and channels by keyword

• Fetch videos from a playlist or channel

• Video, channel and playlist metadata, chapters, and top comments

• Transcripts with timestamps, sliced by time range or chapter, and capped so a three-hour video cannot flood your context

• Search inside a transcript and get back ?t= links that open the video at the exact moment

• Batch tools: transcripts for many videos at once, or a whole-playlist digest

Extract for editing

• Clip a time range without downloading the whole video, cut precisely or on keyframes, by timestamp or chapter name

• Audio clips in mp3, m4a, wav, flac or opus

• Frame capture at any timestamp, without downloading the file

• Subtitle export as SRT, WebVTT or plain text for Premiere, Resolve or CapCut

• Full downloads with quality presets

Keep what you learn (local mode)

• Save summaries and skill notes to a local library

• Read them back, and search across all of them with full-text ranking

• Tag, retag and delete

Build a brain for a channel (local mode)

• Read a whole channel into a searchable corpus of timestamped passages, in any caption language, resumable and safe to interrupt — a second run continues where it stopped and picks up new uploads

• Ask what a creator has said about anything, across every video, and get back the moments themselves with links that open the video there

• Measure the channel: how much was readable, its upload rhythm, its speaking rate, and the phrases it repeats across videos

• Keep a written profile beside the corpus, grounded in passages you can cite

Built to stay working

• WebVTT parsed by the W3C reference implementation, not a hand-written matcher

• Typed, actionable errors — "no captions in en, try: fr, es, de" rather than a wall of yt-dlp stderr

• Timeouts, retry with backoff, and a concurrency limit on every yt-dlp call

• check_health diagnoses missing or outdated yt-dlp and ffmpeg

• Structured output on every tool, plus MCP resources, prompts and completions

Related MCP server: YouTube Translate MCP

Prerequisites

• Node.js 22+

• yt-dlp — required by every tool. brew install yt-dlp (macOS) or pip install -U yt-dlp

• ffmpeg — required for downloads, clip extraction and frame capture. Everything else works without it.

Run the check_health tool to confirm both are installed and current. An outdated yt-dlp is the most common cause of unexplained failures, since YouTube changes frequently; yt-dlp -U fixes most of them.

Installation

Via npm (Recommended)

npm install -g youtube-knowledge-mcp

Via npx (no installation)

Configure directly with npx (see Configuration section).

From source

git clone https://github.com/teobouancheau/youtube-knowledge-mcp.git
cd youtube-knowledge-mcp
npm install
npm run build

Configuration

Local (stdio) -- Claude Desktop, Claude Code, Cursor

Quick Start with npx

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "npx",
      "args": ["-y", "youtube-knowledge-mcp"]
    }
  }
}

With Global Installation

npm install -g youtube-knowledge-mcp

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "youtube-knowledge-mcp"
    }
  }
}

Configuration File Locations

Restart your client after updating configuration.

Remote (HTTP) -- Claude.ai, Claude Mobile, Custom Connectors

The server supports Streamable HTTP transport for remote access via Claude's official connectors.

Every remote setup is your own deployment. There is no shared instance to point a connector at, by design: every call shells out to yt-dlp, so a single host serving other people's traffic is a host YouTube rate-limits for all of them. The button below deploys this repository into your own Render account, in about two minutes and without cloning anything.

Self-hosted

npm run build
npm run start:http

The server listens on PORT (default 3000). Set PORT environment variable to change.

Docker

docker build -t youtube-knowledge-mcp .

TOKEN=$(openssl rand -hex 32) && echo "MCP_AUTH_TOKEN=$TOKEN"
docker run -p 3000:10000 -e MCP_AUTH_TOKEN="$TOKEN" youtube-knowledge-mcp

The token is printed because nothing else will print it: the server logs that a token is required, never its value. Send it as Authorization: Bearer $TOKEN.

The image sets PORT=10000 and exposes it; publish it on whatever host port you like. The build happens inside the image, so no local npm run build first.

Deploy to Render

The button opens Render's Blueprint flow against render.yaml in this repository, which builds the Docker image, points the health check at /health and generates an MCP_AUTH_TOKEN for you. No fork, no clone, no settings to fill in — the service is yours, on your account.

1. Click the button and confirm. Render builds the image and deploys it.

2. Open the service's Environment tab and copy the generated MCP_AUTH_TOKEN. The HTTP transport rejects every request without it, so a URL that leaks is not an open server.

3. Add https://<your-service>.onrender.com/mcp as a custom connector, with Authorization: Bearer <token>.

Worth doing once the service exists: set MCP_ALLOWED_HOSTS to your service's hostname (<your-service>.onrender.com). It cannot be filled in from the Blueprint, since the hostname does not exist until the service does, and it rejects requests arriving under any other name.

Your instance does not follow this repository. The Blueprint sets autoDeployTrigger: off, because auto-deploying would run code pushed here inside your account, under your token, without you reading it first. To take a newer version, use Manual Deploy on the service.

The free plan sleeps after inactivity, so the first call after a pause waits for a cold start. Any paid plan removes that.

Connect via Claude.ai

1. Go to Settings > Connectors

2. Click Add custom connector

3. Enter your server URL (e.g., https://your-app.onrender.com/mcp)

4. Add the Authorization: Bearer <token> header if you set MCP_AUTH_TOKEN

5. Click Add

MCP Tools

33 tools. The 14 read-only ones work over both transports; the 19 that touch your filesystem are registered only in local (stdio) mode, so a remote deployment cannot reach the host's disk.

Every tool returns human-readable text and typed structured output, and reports failures as an actionable message — [NO_CAPTIONS] No "en" captions are available for this video. Call get_transcript again with one of: fr, es, de.

Discovery — remote + local

Transcripts — remote + local

format: "timestamped" prefixes each line with [MM:SS] — use it when you need to cite or link to a moment. maxChars with offset reads a long transcript in pieces instead of returning 100,000+ tokens at once.

Extraction for editing — local only

Clips are cut with --download-sections, so only the byte range covering the window is fetched rather than the whole file. preciseCuts (default true) cuts exactly at the requested times; set it to false for a faster keyframe-aligned cut. All of these require ffmpeg.

Knowledge library — local only

Channel brains — local only

build_brain is the only one that touches the network. The rest resolve a channel from what is already on disk, so they work offline and cost nothing to call.

A brain holds one caption language; pass language to read another, and build a separate brain per language.

since and minDurationSeconds describe the brain, not just the call that passed them. They are re-applied every time, so narrowing one drops the passages of the videos it excludes and widening it reads them back — which is why build_brain is annotated as destructive. Whether a video qualifies is decided from the date and length already recorded, so changing your mind costs no requests until there is something new to fetch. Those values come from each video's own metadata, never from a guess: a flat channel listing does not carry a publication date at all.

build_brain also repairs. If the passage file is lost or truncated, the videos it can no longer account for are read again on the next call rather than being skipped forever as already done.

Prompts

Reusable workflows your client can invoke directly: summarize_video, extract_skill, compare_videos, research_topic, channel_deep_dive, clip_from_quote (find a phrase, then cut the clip around it), and — local only — review_library, create_brain (build a channel's corpus, then write its profile from it) and ask_creator (answer a question strictly from a brain, with citations).

Resources

• youtube://transcript/{videoId} — a timestamped transcript, fetched and cached on first read

• youtube://library/{videoId}/{summary|skill} — a saved note (local only, and enumerable)

• youtube://brain/{channelId}/{manifest|profile} — what a channel brain covers, or the profile written from it (local only, and enumerable)

Error codes

Failures are reported inside the result so the model can read and recover from them, each prefixed with a code and followed by a next step.

Environment variables

All optional.

Library Storage

Content is stored in ~/.youtube-knowledge/:

~/.youtube-knowledge/
├── transcripts/          # Cached timestamped transcripts
│   └── {video_id}.{lang}.json
├── library/              # Saved notes
│   └── {video_id}/
│       ├── metadata.json
│       ├── summary.md
│       └── skill.md
├── brains/               # Channel brains
│   └── {channel_id}/
│       ├── manifest.json # What the brain covers, and where a build stopped
│       ├── chunks.json   # The timestamped passages
│       └── profile.md    # The written account, if one was saved
├── downloads/            # Full downloads
├── clips/                # Extracted clips
├── frames/               # Captured stills
├── subtitles/            # Exported SRT / VTT / TXT
├── index.json            # Library index
└── search-index.json     # Full-text search index

Transcripts are cached for 30 days by default; pass refresh: true to any transcript tool to bypass the cache, or set YOUTUBE_MCP_TRANSCRIPT_TTL_MS.

Every tool that writes files confines its output to your home directory, and outputDir is rejected if it points anywhere else.

Usage Examples

Find a moment and cite it

"Find where this video talks about rate limiting and give me the timestamp:
 https://youtube.com/watch?v=..."

search_transcript returns each match with a link that opens the video at that second, so the claim can be checked rather than taken on trust.

Find a moment and clip it

"Find where she says 'the real bottleneck was the database' and cut me a
 30-second clip around it"

search_transcript locates the moment, extract_clip cuts it. Only the byte range covering the clip is downloaded.

Read one section of a long video

"Summarize just the 'Benchmarks' chapter of this 3-hour podcast"

get_chapters finds the section, then get_transcript with chapter: "Benchmarks" reads only that part instead of the whole thing.

Survey a playlist cheaply

"What does this 40-video course cover, and which three videos should I watch?"

digest_playlist returns metadata and chapters for every video in one call.

Prepare footage for an edit

"Pull these four moments as separate clips and export the subtitles as SRT"

extract_clips cuts all four in one call; export_subtitles writes a file your editor can import.

Build and query a knowledge base

"Summarize this video and save it to my library tagged 'databases'"
"What have I saved about connection pooling?"

save_to_library stores it; search_library searches across everything saved with full-text ranking.

Build a brain for a creator

"Build a brain for @Fireship, then tell me everything they've said about Rust"

build_brain reads the channel into timestamped passages — interrupt it and call it again to continue. ask_brain then answers from what was actually said, returning the moments themselves so every claim can be checked against the video. Run build_brain again a month later and it reads only the new uploads.

Testing

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report, with thresholds enforced

The suite covers the pure logic directly, drives the real server through an MCP client over an in-memory transport, exercises the library against a real temporary filesystem, and snapshots the tool manifest so any change to the public surface shows up as a reviewable diff.

Development

npm run dev        # Watch mode
npm run build      # Build for production
npm run rebuild    # Clean and rebuild
npm start          # Run server (stdio)
npm run start:http # Run server (HTTP)
npm run validate   # Typecheck + lint + format check + test

CI runs the same gate on Node 22 and 24 for every push and pull request, then boots the built server as a real MCP client to verify the manifest.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the project layout, coding standards, and how to add a tool.

Security

The HTTP transport is unauthenticated unless you set MCP_AUTH_TOKEN. See SECURITY.md before exposing it beyond localhost, and to report a vulnerability.

License

MIT License - see LICENSE for details.

Acknowledgments

• yt-dlp for YouTube extraction

• Anthropic for the Model Context Protocol