yt-mcp
A YouTube research MCP server that resolves channels, browses and searches their videos, and extracts transcripts, descriptions, links and engagement stats for citation.
find_channel— resolve a handle (@mkbhd), channel URL,UC...id or name into a channel with its title, URL, description, video count and subscriber count.search_channel_videos— keyword-search within a single channel, with ordering (relevance, date, views, rating, title), result limits (1–50) and publish-date filters; costs 100 quota units per 50 results.list_channel_videos— list a channel's uploads newest first (1–200), optionally narrowed by relative (7d,6m,1y), absolute (2025-01-31) or RFC 3339 dates; much cheaper than searching.get_video_transcript— pull a timestamped transcript where each line starts with a Markdown link that seeks to that moment, so quotes stay clickable and traceable; supports language selection, cue merging (chunk_seconds), start/end windows, and costs no API quota.get_video_details— fetch a video's full description, the unique http(s) links the creator cited, tags, plus view/like/comment counts and caption availability.Flexible references — videos accepted as ids or watch/
youtu.be/shorts URLs; channel lookups memoised for the process lifetime.
Provides tools for searching YouTube channels, listing videos, fetching transcripts with timestamps, and retrieving video details with citations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yt-mcp search MKBHD channel for the latest iphone review"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
working code - the server writes last usage date to usage.json itself, on its first tool call of each day. A stale commit log here means the code is finished, not abandoned. See Usage signal.
Setup
Reads
YOUTUBE_API_KEYfrom.envat the project root;.env.exampleis the template.The key is a Google Cloud API key with "YouTube Data API v3" enabled.
uv syncinstalls.uv run yt-mcpserves MCP over stdio.claude mcp add yt -- uv run --directory "$PWD" yt-mcp, run from the repo root, registers it with Claude Code.
Related MCP server: YouTube MCP
Deployment
designed to by deployed on Prefect Horizon but YouTube api blocks servers IPs for the transcript fetch.
personally running locally to avoid setting up proxy.
Tools
search_channel_videossearches one channel's videos by keyword - search MKBHD channel for the latest iphone review.list_channel_videoslists a channel's videos newest first, filtered by date - everything from the last year.get_video_transcriptextracts a video's transcript with timestamps.get_video_detailsreturns a video's description, with the external links the creator cited pulled out for citation.find_channelresolves a channel and returns its stats.
References
Channels are given as
@mkbhd, a channel URL, aUC...id, or a channel name.Videos are given as an id or any watch /
youtu.be/ shorts URL.Date filters take relative offsets (
7d,6m,1y), dates (2025-01-31), or RFC 3339 timestamps; months and years are 30 and 365 days.
Transcripts
Lines are formatted
[[MM:SS]](watch url with &t=seconds) text, gaining an hour component past an hour -[[03:15]](https://www.youtube.com/watch?v=ID&t=195) the battery is 17% larger than previous year.The timestamp is a Markdown link that seeks to that moment, so a quoted line carries its own clickable citation; the link points at the start of the merged window, not the last cue in it.
chunk_secondsmerges caption cues into windows of that length;0keeps YouTube's raw cues.start_secondsandend_secondsnarrow a long video to one stretch.languagespicks the track by language code; with none given the video's original spoken language is used.Transcripts come from public caption tracks rather than the Data API, so they need no key and cost no quota.
Caption IP blocks
Caption tracks are served to the player rather than to the Data API, so YouTube judges the request by IP instead of by key: it blocks cloud provider ranges outright, and rate limits any single address that pulls transcripts in bulk. Both surface as
TranscriptBlockedError, and both are about the caller, not the video.
Usage signal
This is a signalling device. Not a feature of the server. If you are running yt-mcp for yourself, delete it - see "Removing it" below.
The problem it solves is a presentation one: a repository whose last commit is months old reads as abandoned, whether or not it is.
The middleware notes the UTC date of each tool call and, on the first call of a new date, commits
usage.jsonto this repository through the GitHub contents API. The README badge renders that file.One write per UTC day, not one per call.
records one field:
{"last_used": "2026-08-10"}. A UTC date.
Turning it on
Unset
USAGE_BADGE_TOKENis the default and the recommended state. With no token the middleware is never registered, so nothing inusage.pyruns and a tool call costs exactly what it costs without the feature.With a token set, the signal is on.
USAGE_BADGE_TOKENdeliberately is not namedGITHUB_TOKEN: GitHub Actions injects that name automatically, which would switch the signal on inside CI.The token is a fine-grained personal access token with Contents: read and write on this repository and nothing else. Set it as a host secret next to
YOUTUBE_API_KEY- it never belongs in the repository, and.envis gitignored.REPOSITORYinsrc/yt_mcp/usage.pynames the target. A fork that keeps this module writes to the upstream repository and is refused, which is a reason to delete rather than reconfigure.
Removing it
Five deletions, in any order. Nothing else references any of it.
Delete | |
| the mechanism |
| its tests |
the import and | unregisters it |
| removes the published date and its docs |
| removes the last trace |
httpx in pyproject.toml is there for this feature alone, though it arrives as a fastmcp dependency regardless.
nnel lookups are memoised for the life of the process.
Available Tools
5 toolsfind_channelA
Resolve a channel handle, URL, id or name to a channel with its stats.
Useful on its own to confirm which channel a name refers to before searching.
Inputs: channel (required). Returns: A resolved YouTube channel.
get_video_detailsA
Get a video's full description, extracted links, tags and engagement counts.
The links list is what the creator cited in the description — sources, products, sponsors and their own other videos.
Inputs: video (required). Returns: A video plus its full description and engagement counts.
get_video_transcriptA
Get a video's transcript as timestamped lines you can quote and cite.
Every line starts with a Markdown link that seeks to that moment, so quoting a timestamp back keeps claims traceable and clickable — e.g. "at [03:15] he says the battery is 17% larger than last year". Reproduce those links verbatim rather than rewriting them as plain text. Narrow long videos with start_seconds and end_seconds. Reads public caption tracks, so it costs no API quota.
Inputs: video (required), languages, end_seconds, chunk_seconds, +1 more. Returns: A timestamped transcript.
list_channel_videosA
List a channel's uploads newest first, optionally within a date range.
Example: everything MKBHD posted in the last year, via published_after='1y'.
Inputs: channel (required), max_results, published_after, published_before. Returns: A page of videos belonging to one channel.
search_channel_videosA
Search one channel's videos by keyword, e.g. the latest iPhone review on MKBHD.
Costs 100 YouTube quota units per 50 results. When you want recent uploads and have no keyword, use list_channel_videos instead — it is 100x cheaper.
Inputs: query (required), channel (required), order, max_results, +2 more. Returns: A page of videos belonging to one channel.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct action: channel resolution, keyword search, recent listing, transcript retrieval, and metadata/details. The only potential confusion is between search_channel_videos and list_channel_videos, but their descriptions clearly separate keyword-based search from recent-upload listing.
All five tools follow a consistent verb_noun pattern with snake_case: find_channel, search_channel_videos, list_channel_videos, get_video_transcript, get_video_details. The verbs are appropriate and predictable for their functions.
Five tools is a well-scoped surface for a YouTube research/retrieval server. Each tool covers a distinct part of the workflow without excessive overlap or unnecessary additions.
The core read-oriented workflow is covered: resolve a channel, find/list videos, fetch transcripts, and get detailed metadata. Minor gaps exist, such as no direct cross-YouTube search or playlist support, but common video research tasks are fully supported.
Maintenance
Related MCP Connectors
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
Real-time YouTube transcripts, comments, channels & video search MCP. Local npx or hosted OAuth.
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with the YouTube Data API, allowing users to search videos, get video and channel details, analyze trends, and fetch video transcripts.-
- AlicenseAqualityDmaintenanceAn MCP server that enables users to retrieve YouTube transcripts and perform video or channel searches without requiring Google API keys. It supports transcript chunking and provides tools for detailed video content analysis and channel metadata extraction.54MIT
- AlicenseBqualityBmaintenanceAn MCP server that enables the extraction of transcripts and detailed metadata from YouTube videos. It allows users to retrieve video information like titles and descriptions, as well as transcripts with optional timestamps and language selection.2MIT
- AlicenseAqualityBmaintenanceMCP server that provides YouTube video data to AI agents, supporting search, metadata, comments, and transcripts without an API key.660 npmISC