Skip to main content
Glama

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.

  1. Make sure uv is installed. Run uv --version. If that fails, install it:

    • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh, then open a new shell or run source $HOME/.local/bin/env

    • Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. 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 dQw4w9WgXcQ
  3. Register 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 mcp
    • Codex CLI:

      codex mcp add yt-transcript -- uvx --from git+https://github.com/PinkiNice/youtube-search-mcp yt-transcript mcp
    • Clients 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"]
  4. Restart or reload the client. Check that the yt-transcript server lists the tools below. If a GUI app can't find uvx, put its absolute path in command. Run which uvx (macOS/Linux) or where 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

get_transcript

Transcript of a video. Defaults to plain text without timestamps. Options: language, format=json, include_timestamp, include_metadata

get_video_info

Title, author, thumbnail and the transcript languages available

search_youtube

Search for videos, channels, playlists or movies, with sort and filters

resolve_channel

Turn a @handle or URL into a UC… channel ID

search_channel

Search for videos within one channel

list_channel_videos

A channel's uploads, shorts or streams, optionally sorted

get_channel_latest

The 15 newest uploads, with exact dates and view counts (RSS)

list_playlist_videos

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 diagnostics

fetch 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/health

Listing 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

  1. Check GET /health. The cooldowns list shows which client and proxy pairs are paused after a bot check or rate limit. Check the X-Served-By header to see which strategy still works.

  2. Update yt-dlp, which is the fallback: uv lock --upgrade-package yt-dlp && uv sync.

  3. Set YT_PROXIES to one or more residential proxies, separated by commas. Requests rotate across them.

  4. Export a cookies.txt from a throwaway YouTube account and set YT_COOKIES_FILE. The yt-dlp fallback uses it. It also unlocks age-restricted videos.

  5. If every client returns UNPLAYABLE or ERROR for videos that should work, refresh the client versions in innertube.PLAYER_CLIENTS. Copy them from yt-dlp's INNERTUBE_CLIENTS in .venv/lib/python3.12/site-packages/yt_dlp/extractor/youtube/_base.py.

  6. If stderr shows reason=empty_body for every client, YouTube is demanding PO tokens. Run uv add bgutil-ytdlp-pot-provider and docker run -d -p 4416:4416 brainicism/bgutil-ytdlp-pot-provider so 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

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers