youtube-research-mcp

An MCP server that lets Claude research YouTube channels and read video transcripts, without a YouTube API key and without rendering a browser.

Legal status - read this before using it

This talks to YouTube through yt-dlp rather than YouTube's official Data API, which is outside what YouTube's Terms of Service contemplate as sanctioned automated access. That's a real thing to know, not a formality:

• yt-dlp itself is legal to build on and distribute. It's public domain (Unlicense), survived a 2020 DMCA takedown attempt (GitHub reinstated it after EFF intervention, on the grounds it has substantial non-infringing uses), and has millions of users. Individual open-source tools built on it, used for personal research, have a long track record of being left alone.

• What has consistently drawn legal action is monetizing or centralizing access to YouTube content - commercial "download as a service" sites get sued and shut down repeatedly. This project is released free, MIT-licensed, meant to be cloned and run locally by each user against their own network - not offered as a hosted service. Reselling access to it, or running it as a shared service many people connect to, meaningfully changes that risk picture and isn't something this project endorses.

• This is not legal advice, and no one associated with this project is liable for how you use it - see the LICENSE's warranty disclaimer. If you're planning anything beyond personal research use, get real legal review first.

• YouTube's anti-automation measures (PO Tokens, bot-checks, IP-based rate limiting) are real, active, and have escalated in 2026 specifically - see "Notes and limits" below. This tool's reliability is inherently coupled to yt-dlp's ability to keep up; periodic maintenance (pip install --upgrade yt-dlp) is normal, not a sign something is broken.

Related MCP server: VidLens

How it works

Uses yt-dlp to talk to YouTube's own internal JSON endpoints directly, rather than rendering a page in a browser or calling the official Data API - no API key needed. Everything is read only. Video listings come from a flat playlist extraction (titles and IDs only, no video data), and transcripts are read straight from the caption track into memory. Only get_video_frames touches disk, and only a temp file it deletes when the server exits.

Tools

list_channel_videos(channel_url, max_results=50, resolve_all_dates=False)

Lists a channel's uploads, newest first.

• channel_url accepts a handle (@mwganson), a bare name (mwganson), a channel ID (UCLNPmhURJNIm9wsRunKM8mA), any youtube.com channel URL with or without a /videos, /shorts or /streams tab, or a playlist URL.

• max_results is 1 to 1000, default 50.

• resolve_all_dates controls how upload dates are filled in. See the note below.

Returns channel, channel_id, channel_url, total_videos, count, and a videos list. Each video has video_id, title, url, duration_seconds, duration, view_count, and upload_date.

get_video_transcript(video_url_or_id, language="en", include_timestamps=False, max_chars=0)

Fetches a video's transcript as clean plain text.

• video_url_or_id accepts an 11 character video ID or any watch, youtu.be, shorts, live or embed URL.

• language is the preferred caption language code. Regional variants match too, so en will accept en-US. If the language is missing entirely, the first available track is used.

• include_timestamps puts [H:MM:SS] at the start of each paragraph, which is what you want if you plan to cite a moment in the video.

• max_chars truncates the result. 0 means no limit. Set it when you are scanning many videos, because a long tutorial can run tens of thousands of characters.

A human written caption track is preferred, and YouTube's auto generated one is the fallback. The result reports which you got in transcript_kind, along with title, channel, duration, upload_date, language, char_count, truncated, and the transcript itself as paragraphs of roughly 30 seconds each.

get_video_frames(video_url_or_id, timestamps=None, every_seconds=0, max_frames=6, width=1280, max_height=720, quality=4, output_dir=None, include_images=True)

Returns actual images of what the video shows at chosen moments, and can save them to disk in the same call.

Transcripts alone cannot capture a screen based tutorial. "Click this, then drag it here" has no referent in text. Toolbar clicks are usually silent. Typed dialog values are rarely spoken. And auto captions mangle exactly the technical terms you need, which you can see for yourself in the transcripts this tool returns, where PDWrapper comes through as "pt wrapper" and FreeCAD as "free cad".

So the intended workflow is two tiers, and doing it in this order is what keeps it cheap.

1. Broad and cheap. get_video_transcript(..., include_timestamps=True) across as many videos as you like, to find which videos and which minutes matter.

2. Narrow and visual. get_video_frames(video_id, timestamps=[...]) on just those moments.

• timestamps is a list of 'S', 'M:SS' or 'H:MM:SS' strings, taken from step 1.

• every_seconds samples evenly instead, for surveying an unfamiliar video. Explicit timestamps are far cheaper.

• max_frames caps the result at 1 to 50, default 6. Every frame costs context when returned inline - see include_images below if you just want files on disk.

• width is the output width, 320 to 1920, default 1280. Do not go below about 960 if you need to read menu labels.

• max_height is the source stream height fetched, default 720. That is enough to read a CAD toolbar and keeps the fetch small.

• output_dir saves every captured frame as a JPEG to a local directory (created if it doesn't exist), named {video_id}_{HH-MM-SS}.jpg. Written straight from the same ffmpeg output already produced for the in-context images - no separate download or re-extraction needed. None (default) saves nothing, same as before this existed.

• include_images defaults to True (frames returned inline, as always). Set False only alongside output_dir to skip the context cost when you just want files saved, not looked at in this conversation.

Returns a text summary followed by one image per timestamp (unless include_images is False). Frames that fail to capture, or capture but fail to save, are noted in the summary rather than failing the whole call.

search_youtube(query, max_results=20, broader_terms=None, auto_broaden=True)

Keyword search, for when you do not know the channel or video yet. Returns the same video fields minus the upload date, plus relevance (0.0-1.0) and found_via. Use it to find candidates, then feed a result's channel or URL to one of the other two tools.

Widens itself automatically when a narrow query comes back empty or comes back with results that don't look on-topic — no need to remember to retry with a blunter query by hand. It runs your query as written, and if that's thin it also tries mechanical shortenings of your own words (dropping academic register terms like "optimization", trying the head and the lead of the phrase) plus any broader_terms you pass, then re-ranks everything by topic-word overlap so on-topic results surface and noise gets dropped again.

Always pass broader_terms when the topic matters — 2-3 alternate phrasings (practitioner slang, the blunt everyday name, adjacent tool/software names), e.g. broader_terms=["clay 3d printing", "paste extruder"]. This function is plain Python with no model in it, so it cannot invent a synonym or know that two phrasings name the same subject — only the calling session can do that. Without broader_terms, only mechanical shortening is possible, which is real but weaker.

Set auto_broaden=False to get the exact old behavior: your query, nothing else.

Install and register

The server has its own virtual environment on purpose, so installing yt-dlp here cannot disturb any other MCP server's dependencies. You'll also need ffmpeg on PATH for get_video_frames — the other three tools don't need it.

Windows (PowerShell):

cd path\to\youtube-research-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
winget install Gyan.FFmpeg   # if ffmpeg isn't already on PATH

macOS / Linux:

cd path/to/youtube-research-mcp
python3 -m venv .venv
./.venv/bin/python -m pip install .
brew install ffmpeg   # or apt-get install ffmpeg / your distro's package manager

That installs a yt-research-mcp console command into the venv - register it with Claude Code (user scope, so it is available in every project), replacing path/to with wherever you actually cloned this:

claude mcp add youtube-research --scope user -- `
  path\to\youtube-research-mcp\.venv\Scripts\yt-research-mcp.exe

claude mcp add youtube-research --scope user -- \
  path/to/youtube-research-mcp/.venv/bin/yt-research-mcp

Or add it by hand to ~/.claude.json (Windows path shown; use forward slashes on macOS/Linux and drop the .exe):

"youtube-research": {
  "type": "stdio",
  "command": "C:\\path\\to\\youtube-research-mcp\\.venv\\Scripts\\yt-research-mcp.exe"
}

Testing

Editable install first, so test changes to the code without reinstalling:

.\.venv\Scripts\python.exe -m pip install -e .     # Windows, once
.\.venv\Scripts\python.exe test_smoke.py

./.venv/bin/python -m pip install -e .              # macOS/Linux, once
./.venv/bin/python test_smoke.py

This hits YouTube for real, with no mocking, deliberately - every real failure mode found and fixed in this project (the cookie-database lock, the live-stream hang, the transient 403 on a large fetch) only showed up by testing against the real service; a mocked suite would have asserted the code does what it was written to do, not caught where that turned out to be wrong. It lists two real channels, pulls a real transcript, runs a search, checks every URL shape the parsers are supposed to handle, and rejects whatever's currently live on a 24/7 stream in a couple of seconds rather than attempting to download it. Prints a PASS or FAIL line per check, exits non zero if anything fails.

The real cost of that choice: every run needs network access and YouTube being up, and there's no fast offline loop for iterating on unrelated code. Accepted deliberately rather than fixed - an offline/mocked layer wouldn't have caught anything this pass found, and network-dependent tests are the right shape for a tool whose entire job is talking to a real external service.

Notes and limits

Upload dates. A flat channel listing does not carry upload dates, which is the tradeoff that makes it fast. So by default the server fills them in from the channel's public RSS feed, which is one extra cheap request and covers roughly the 15 most recent videos. Older videos come back with upload_date of null. Set resolve_all_dates=True to date the whole list, but that costs about one request per video, so keep max_results small when you do.

Total video count. total_videos is whatever YouTube reports and is often null. The count field is always accurate for what was returned.

Videos with no captions. Some videos genuinely have no caption track, not even an auto generated one. The server says so explicitly rather than returning an empty string, so there is no point retrying those.

If YouTube asks for a sign in. YouTube sometimes demands a signed in session and yt-dlp will report "Sign in to confirm you're not a bot". Tested against 90 real, distinct videos at meaningful concurrency (10 parallel workers) on 2026-08-08 without ever triggering it - yt-dlp calls YouTube's internal API with client emulation rather than scraping the rendered page, which is a different code path from what the casual "browser automation" bot-check usually catches. So the trigger itself is unverified here; what is verified is the fix and a real failure mode in it.

YT_DLP_COOKIES_FROM_BROWSER=chrome    # or firefox, edge - see the caveat below
YT_DLP_COOKIEFILE=/path/to/cookies.txt

YT_DLP_COOKIES_FROM_BROWSER fails outright while that browser is running, confirmed on this machine: with Chrome open, yt-dlp cannot copy its cookie database (PermissionError, since Chrome holds an exclusive lock on it) and the read fails completely - not silently, it raises CookieLoadError. Pointing at a browser that happens to be closed (edge, when Edge wasn't running) worked cleanly. Since Chrome being open is the normal case, not an edge case, YT_DLP_COOKIEFILE is the more reliable choice - export cookies.txt with a browser extension once, and it works regardless of what's running. The server now recognizes this specific failure (_friendly_error's CookieLoadError branch) and returns an actionable message telling you to close the browser or switch to YT_DLP_COOKIEFILE, instead of crashing with a raw Python traceback the way it did before this was found and fixed.

Why frames are fetched rather than seeked. The obvious design is to have ffmpeg seek the remote stream URL and range request only the bytes it needs. That does not work. YouTube binds a stream URL to the player client that requested it and refuses everyone else, so handing the URL to ffmpeg gets HTTP 403 or a stall that never finishes. yt-dlp's own download_ranges hits the same wall, because it shells out to ffmpeg too. Forcing the android client produces a URL ffmpeg can fetch, but that client only offers 360p, which is too coarse to read a menu label.

What does work is letting yt-dlp fetch the stream itself, since it holds the matching client session. That is cheap because the stream is video only, with no audio track requested. Measured on a 31 minute 720p tutorial: 32 MB in 5.7 seconds, then frames come off the local file in well under a second each. Both the file and its metadata are cached for the life of the server process (3 videos maximum), so a second call on an already-fetched video needs no network round trip at all - measured 0.1 seconds against 10.3 cold (an earlier version of this cache kept only the file and refetched metadata on every hit, which still worked but cost about 1.3s per warm call - fixed in the pre-publish audit).

ffmpeg is required for frames only. The other three tools do not need it. If it is missing, get_video_frames says so and tells you to run winget install Gyan.FFmpeg.

Live streams are rejected before any fetch is attempted. A currently-live or not-yet-started broadcast has no end, so "download the stream" never finishes - confirmed real 2026-08-08 against Lofi Girl's 24/7 stream: it ran for about 90 seconds before ffmpeg exited with a bare, unhelpful code 1. get_video_frames now checks is_live/live_status first and fails in about 1-2 seconds with a clear reason instead. A was_live video (the broadcast has ended and YouTube published the replay) works normally - only genuinely open-ended streams are rejected.

Playlist URLs work end to end, confirmed against a real 11-video playlist - listing, ordering, and channel/count metadata all correct. Their videos follow the same upload-date rule as any other listing (recent ones resolve free via RSS, older ones need resolve_all_dates=True) - there's nothing playlist-specific about it, an older video is an older video whether reached by channel or by playlist.

Region-blocked videos: the fallback path is proven, the specific message is not. Two real attempts to trigger an actual geo-block both missed: a video documented in yt-dlp's own issue tracker as geo-restricted is now blocked everywhere by a copyright claim instead, and BBC's YouTube channel turned out not to be region-locked the way BBC iPlayer is. What is proven is that the general failure path handles it safely - any YoutubeDLError yt-dlp raises comes back as a clean message, never a crash - and _friendly_error has a specific branch for YouTube's documented "not available in your country" phrasing, matched by text since yt-dlp has no dedicated exception type for this. That specific branch is unverified against a real occurrence.

Transient failures on both fetch paths are retried automatically. The large-stream download in get_video_frames (the other three tools are lightweight metadata calls, and 90 of those in a row - including a 10-worker concurrent burst - produced zero failures during testing). Confirmed real on 2026-08-08: a 4-hour video's stream fetch returned HTTP 403 once, then succeeded seconds later with nothing else changed - a signed download URL failing in a way only a fresh extraction clears, not something yt-dlp's own extractor_retries covers, since that only retries metadata calls. _local_stream now retries the whole extraction (not just the byte fetch) up to 3 times with backoff - but skips retrying entirely for failures no retry could fix (cookie lock, live stream, private/unavailable, region-block), so those still fail in one attempt, not three. get_video_transcript's caption-file fetch got the same retry logic in the pre-publish audit, on the same reasoning (caption URLs are signed and time-limited the same way stream URLs are) even though no failure was ever observed there in testing - proactive, not reactive.

Only youtube.com/youtu.be URLs are ever accepted. list_channel_videos hands whatever URL it's given to yt-dlp's extractor, which has a generic fallback capable of fetching arbitrary URLs, not just YouTube's. Every full-URL input is checked against the actual host before anything else happens with it, and a non-YouTube host raises ValueError immediately. This matters specifically because MCP tools can be called by an agent acting on content it read elsewhere - without this check, a crafted playlist URL pointing somewhere else entirely could have made this server issue an outbound request to an attacker-chosen destination. Added in the pre-publish audit; the video-ID path (get_video_transcript, get_video_frames) never had this exposure in the first place, since it only ever extracts an 11-character ID and always re-embeds it into a hardcoded youtube.com URL, discarding whatever host the input actually had.

Two smaller pre-publish audit fixes, both defensive rather than reactive to an observed failure. The temp directory get_video_frames downloads into is now swept for leftovers from a prior run's unclean exit (a forceful kill doesn't fire Python's atexit, so a long-lived install could otherwise accumulate one stray directory per crash). And the stream/metadata cache is now protected by a lock - the MCP stdio transport is normally one request at a time, but nothing in the protocol guarantees a client won't ever pipeline overlapping tool calls, and the cache's check-then-act sequence wasn't safe against that without one.

Keeping yt-dlp current. YouTube changes its internals regularly and yt-dlp keeps up, so if extractions start failing the first thing to try is an upgrade.

.\.venv\Scripts\python.exe -m pip install --upgrade yt-dlp    # Windows

./.venv/bin/python -m pip install --upgrade yt-dlp             # macOS/Linux

Verified

Tested end to end on 2026-08-08 against @mwganson and @MangoJellySolutions. Both listed correctly with real dates and durations. A full auto generated transcript came back from Tbiu_rMJolk, and search returned results. Frames were pulled from Xybk1EJfwHk (Reverse Engineering an STL Fan Impeller) at five transcript chosen moments in 5 seconds, and were legible enough to read the workbench selector, the model tree, property values and the status bar dimensions.

A real MCP stdio session completed a handshake, listed all four tools, returned live listing data, and returned mixed text plus image content from get_video_frames. All four of its error paths (bad timestamp, no timestamp given, timestamp past the end of the video, unavailable video) return proper MCP errors with actionable messages.

Hardening pass, 2026-08-08. Four rough edges from the first verification round, worked through against real content, not synthetic tests - see "Notes and limits" above for the full detail on each:

One bug found while fixing another: the live-stream check itself could crash unhandled in the same cookie-lock scenario, because it was a bare call with no except. Caught by testing the fix against the earlier finding, not by inspection - fixed in the same pass.