yt-transcript
Provides tools for retrieving YouTube transcripts and video info, searching YouTube videos/channels/playlists/movies, resolving channels, listing channel uploads/shorts/streams and latest videos via RSS, and listing playlist videos. Requests go directly from the local machine to YouTube without an API key.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
youtube-search-mcp
A YouTube transcript service that runs on your own machine. You can use it as an MCP server for AI agents, or as an HTTP API that copies the TranscriptAPI.com v2 REST API. It covers transcripts, video info, search, channel lookups (resolve, search, videos, latest via RSS) and playlist listing. It needs no API key and has no usage credits. Requests go straight from your machine to YouTube.
AI agent installing this? Follow Install as an MCP server. The installed command is called
yt-transcript.
Install as an MCP server
You don't need to clone the repo. uvx fetches the code, installs
Python 3.12 if it's missing, and runs the server over stdio.
Make sure
uvis installed. Runuv --version. If that fails, install it:macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh, then open a new shell or runsource $HOME/.local/bin/envWindows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Smoke test. This should print one JSON line containing
"language": "en"and"segments_count". The first run takes about 30 seconds while dependencies install.uvx --from git+https://github.com/PinkiNice/youtube-search-mcp yt-transcript fetch dQw4w9WgXcQRegister the server with your MCP client. The command is always
uvx --from git+https://github.com/PinkiNice/youtube-search-mcp yt-transcript mcp.Claude Code:
claude mcp add yt-transcript --scope user -- uvx --from git+https://github.com/PinkiNice/youtube-search-mcp yt-transcript mcpCodex CLI:
codex mcp add yt-transcript -- uvx --from git+https://github.com/PinkiNice/youtube-search-mcp yt-transcript mcpClients configured with JSON: Claude Desktop (
claude_desktop_config.json), Cursor (~/.cursor/mcp.json), Windsurf, Cline, Gemini CLI (~/.gemini/settings.json) and others. VS Code (.vscode/mcp.json) uses"servers"instead of"mcpServers"and adds"type": "stdio".{ "mcpServers": { "yt-transcript": { "command": "uvx", "args": ["--from", "git+https://github.com/PinkiNice/youtube-search-mcp", "yt-transcript", "mcp"] } } }Codex
~/.codex/config.toml, if you prefer editing the file:[mcp_servers.yt-transcript] command = "uvx" args = ["--from", "git+https://github.com/PinkiNice/youtube-search-mcp", "yt-transcript", "mcp"]
Restart or reload the client. Check that the
yt-transcriptserver lists the tools below. If a GUI app can't finduvx, put its absolute path incommand. Runwhich uvx(macOS/Linux) orwhere uvx(Windows) to find it.
Settings are optional and passed as environment variables: -e KEY=value for claude mcp add, or
an "env": {…} object in JSON configs. The useful ones are YT_PROXIES, YT_COOKIES_FILE and
LOG_LEVEL=WARNING (quieter stderr). See .env.example for the full list. The cache
is stored at ~/.cache/yt-transcript/cache.sqlite3.
To update to the latest commit, run the smoke test once with uvx --refresh --from …. To pin a
version, use git+https://github.com/PinkiNice/youtube-search-mcp@<tag-or-commit>.
Tools
All tools are read-only. Errors come back as JSON {"detail", "code"}, the same codes the HTTP API
uses.
Tool | Purpose |
| Transcript of a video. Defaults to plain text without timestamps. Options: |
| Title, author, thumbnail and the transcript languages available |
| Search for videos, channels, playlists or movies, with sort and filters |
| Turn a |
| Search for videos within one channel |
| A channel's uploads, shorts or streams, optionally sorted |
| The 15 newest uploads, with exact dates and view counts (RSS) |
| The videos in a playlist |
Listing tools return a continuation_token. To get the next page, pass it as continuation on its
own.
Related MCP server: YouTube for AI Agents
Run from a clone (HTTP API, development)
uv sync
uv run yt-transcript serve # HTTP API on 127.0.0.1:8000 (Swagger UI at /docs)
uv run yt-transcript mcp # MCP server over stdio
uv run yt-transcript fetch <video> # fetch one transcript from the command line, for diagnosticsfetch options: --language en,de, --clients IOS,ANDROID, --no-ytdlp, --no-cache and
--full (prints the whole transcript). It prints one JSON object and exits with status 1 on an
API error.
Settings come from environment variables or a .env file. See .env.example for
every variable and its default. When API_KEY is set, each /api/v2 request must send
Authorization: Bearer <API_KEY>.
Tests run offline from saved fixtures: uv run pytest -q.
Endpoints
B=localhost:8000/api/v2/youtube
curl "$B/transcript?video_url=https://youtu.be/dQw4w9WgXcQ&format=text&send_metadata=true&language=en,asr"
curl "$B/info?video_url=dQw4w9WgXcQ"
curl "$B/search?q=climate%20change&type=video&sort=views&upload_date=month&duration=long&features=hd,cc"
curl "$B/channel/resolve?input=@TED"
curl "$B/channel/search?channel=@TED&q=AI"
curl "$B/channel/videos?channel=@TED&tab=videos&sort=popular"
curl "$B/channel/latest?channel=@TED"
curl "$B/playlist/videos?playlist=PL68492A0FC99185C7"
curl localhost:8000/healthListing endpoints return a continuation_token. Pass it back as continuation= to get the next
page.
Language codes: en picks the manual English track. If there is none, it falls back to
auto-generated English, unless you pass language_fallback=false. asr picks any auto-generated
track, and asr-en picks auto-generated English.
Transcript responses carry two extra headers. X-Cache-Status is HIT or MISS. X-Served-By
says where the transcript came from: innertube:<CLIENT>, yt-dlp or cache.
Errors look like {"detail": "...", "code": "..."}. A 408 temporarily_blocked response means
YouTube blocked every attempt. Retry after the Retry-After interval.
When YouTube blocks you
Check
GET /health. Thecooldownslist shows which client and proxy pairs are paused after a bot check or rate limit. Check theX-Served-Byheader to see which strategy still works.Update yt-dlp, which is the fallback:
uv lock --upgrade-package yt-dlp && uv sync.Set
YT_PROXIESto one or more residential proxies, separated by commas. Requests rotate across them.Export a
cookies.txtfrom a throwaway YouTube account and setYT_COOKIES_FILE. The yt-dlp fallback uses it. It also unlocks age-restricted videos.If every client returns
UNPLAYABLEorERRORfor videos that should work, refresh the client versions ininnertube.PLAYER_CLIENTS. Copy them from yt-dlp'sINNERTUBE_CLIENTSin.venv/lib/python3.12/site-packages/yt_dlp/extractor/youtube/_base.py.If stderr shows
reason=empty_bodyfor every client, YouTube is demanding PO tokens. Runuv add bgutil-ytdlp-pot-provideranddocker run -d -p 4416:4416 brainicism/bgutil-ytdlp-pot-providerso the yt-dlp fallback can mint tokens.
Disclaimer
This project is not affiliated with or endorsed by YouTube or Google. It reads public data through the same endpoints YouTube's own apps use. Automated access may conflict with YouTube's Terms of Service, so use it for personal, low-volume purposes and at your own risk.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
YouTube for AI agents: transcripts, comments, video stats, channel monitor, Shorts captions.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
YouTube transcripts for AI agents: 150+ languages, AI transcription fallback, search, summaries.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to fetch transcripts, metadata, and download videos/audio from YouTube without API keys.33MIT
- AlicenseAqualityDmaintenanceEnables AI agents to search, watch, summarize, clip, and extract transcripts from YouTube videos, all without needing an API key or leaving the chat.968Apache 2.0
- AlicenseAqualityBmaintenanceAllows AI agents to fetch, search, and summarize YouTube video transcripts without an API key, including chapter summaries.4MIT
- AlicenseAqualityBmaintenanceEnables AI agents to search videos, retrieve metadata and transcripts, pinpoint exact moments via hybrid semantic search, and conduct multi-video research with timestamp deep links—all without YouTube API keys.51MIT