youtube-transcript-mcp

A local MCP (Model Context Protocol) server that lets Claude search YouTube and fetch video transcripts/captions — entirely on your own machine, with no Google API key and no quota limits.

Features

• search_videos(query, max_results=10) — Search YouTube by keyword. Scrapes the public search results page, so no API key or quota is needed.

• list_captions(url_or_id) — List every available caption track (manual and auto-generated) for a video, with language codes.

• get_transcript(url_or_id, languages=["ko", "en"]) — Fetch the transcript text for a video. Prefers manually-created captions, falls back to auto-generated ones, in the given language priority order.

All three accept either a bare 11-character video ID or any common YouTube URL format (youtube.com/watch?v=..., youtu.be/..., /shorts/..., etc.).

Because this runs on your own machine (not a cloud container), it also avoids the "YouTube is blocking requests from your IP" error that hosted/cloud IPs often run into.

Related MCP server: YouTube Transcript MCP Server

Requirements

• Python 3.8 or newer

• Windows with PowerShell (for the included installer) — the script itself is plain Python and runs anywhere

Quick install (Windows / PowerShell)

git clone https://github.com/<your-username>/youtube-transcript-mcp.git
cd youtube-transcript-mcp
./install.ps1

The script will:

1. Find a working Python 3.8+ interpreter on your system.

2. Create an isolated virtual environment in .venv.

3. Install the pinned-minimum dependencies from requirements.txt.

4. Print the exact JSON block to paste into your claude_desktop_config.json.

If you'd rather install into your system/global Python instead of a virtual environment:

./install.ps1 -NoVenv

Manual install (any OS)

pip install "mcp[cli]" youtube-transcript-api requests

Then register the server in claude_desktop_config.json (found at %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "youtube-transcript-local": {
      "command": "python",
      "args": ["C:\\absolute\\path\\to\\youtube_transcript_mcp.py"]
    }
  }
}

Fully quit and restart Claude Desktop afterward.

Version compatibility

This server is written to keep working across upgrades of its dependencies rather than pinning exact versions:

• Supports both mcp v1.x (FastMCP) and v2.x (MCPServer) — whichever is installed.

• Supports both youtube-transcript-api v0.6.x and v1.0+, which changed several internal APIs (instance vs. classmethod, dict vs. object transcript segments, exception import paths).

• Uses from __future__ import annotations so modern type hints (list[dict]) don't break on older Python 3.8/3.9 interpreters.

Notes / limitations

• search_videos works by parsing the ytInitialData JSON embedded in YouTube's public search page. It needs no login or key, but if YouTube changes that page's internal structure, the tool will return a clear [ERROR] message rather than silently failing — open an issue if that happens.

• Some videos have captions disabled entirely, or only offer auto-generated captions in a language you didn't ask for; get_transcript will fall back through translation where possible and say plainly when nothing is available.

License

MIT — see LICENSE.