# 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.

## 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)

```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:

```powershell
./install.ps1 -NoVenv
```

## Manual install (any OS)

```bash
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):

```json
{
  "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`.