yt-mcp

MCP server that lets you search and list YouTube channel videos, fetch video details, and extract transcripts with timestamps using natural language.

README

Reads YOUTUBE_API_KEY from .env at the project root; .env.example is the template.
The key is a Google Cloud API key with "YouTube Data API v3" enabled.
uv sync installs.
uv run yt-mcp serves MCP over stdio.
claude mcp add yt -- uv run --directory "$PWD" yt-mcp, run from the repo root, registers it with Claude Code.

main.py is the entrypoint hosts load, and fastmcp.json points at main.py:mcp.
Set the host's entrypoint to main.py:mcp — src/yt_mcp/server.py holds a bare server instance, because hosts load the entrypoint by file path and never run the package __init__.py that registers the tools.
YOUTUBE_API_KEY is read from the environment, so set it as a host secret; there is no .env in a deployment.
uv run fastmcp inspect main.py:mcp shows what a host will see, tool count included.

search_channel_videos searches one channel's videos by keyword — search MKBHD channel for the latest iphone review.
list_channel_videos lists a channel's videos newest first, filtered by date — everything from the last year.
get_video_transcript extracts a video's transcript with timestamps.
get_video_details returns a video's description, with the external links the creator cited pulled out for citation.
find_channel resolves a channel and returns its stats.

Channels are given as @mkbhd, a channel URL, a UC... 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.

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_seconds merges caption cues into windows of that length; 0 keeps YouTube's raw cues.
start_seconds and end_seconds narrow a long video to one stretch.
languages picks 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.

The default daily quota is 10,000 units.
search_channel_videos costs 100 units per 50 results, plus 1 to hydrate them.
list_channel_videos walks the channel's uploads playlist and costs 1 unit per 50 videos walked, plus 1 per 50 hydrated.
find_channel and get_video_details cost 1 unit.
get_video_transcript costs nothing.
Channel lookups are memoised for the life of the process.

uv run pytest runs the suite.
lint-py src tests runs ruff format, ruff check, ty and complexipy.
The Data API layer is covered against a faked client; only the transcript path touches the network.