youtube-playlist-mcp
by xoliddev
README.md
# youtube-playlist-mcp
**English** · [O'zbekcha](README.uz.md)
Give Claude a whole YouTube playlist to read. A tiny **MCP server** that lists the videos of any public playlist and fetches their transcripts, so you can ask things like *"Summarise every lecture in this course"* or *"Which video explains closures, and what does it say?"*
> **MCP** (Model Context Protocol) is the open standard that lets AI assistants like Claude call external tools and data sources.
Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk), [yt-dlp](https://github.com/yt-dlp/yt-dlp) and [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api). Runs on your own machine; a Cloudflare Tunnel makes it reachable from claude.ai without opening ports or deploying anything.
```text
Claude (claude.ai / Desktop / Code)
│ HTTPS, Streamable HTTP
▼
Cloudflare Tunnel ──► 127.0.0.1:8000/mcp ──► yt-dlp / youtube-transcript-api ──► YouTube
(playlist_mcp.py)
```
## Tools
| Tool | Arguments | Returns |
| --- | --- | --- |
| `get_playlist_videos` | `playlist_url: str` | Playlist title, video count, and one line per video: position, ID, title, watch URL. Uses yt-dlp flat extraction, so it is fast and downloads nothing. |
| `get_multiple_transcripts` | `video_ids: list[str]` (max 5), `languages: list[str] = ["uz", "ru", "en", "tr"]` | Plain-text transcript for each video, choosing the first available language in the given order. Videos without captions are reported inline instead of failing the whole call. |
The 5-video cap keeps each response small enough for the model's context; Claude simply calls the tool several times for longer playlists.
## Install
Requires Python 3.10+.
```bash
git clone https://github.com/xoliddev/youtube-playlist-mcp.git
cd youtube-playlist-mcp
python -m venv .venv
.venv\Scripts\activate # macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
```
## Run locally
```bash
python playlist_mcp.py
# MCP endpoint: http://127.0.0.1:8000/mcp
```
Quick check with the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://127.0.0.1:8000/mcp
```
### Configuration
All settings are environment variables; nothing is hard-coded.
| Variable | Default | Meaning |
| --- | --- | --- |
| `MCP_HOST` | `127.0.0.1` | Interface to bind. Keep it local; the tunnel connects to it. |
| `MCP_PORT` | `8000` | Port. |
| `MCP_ALLOWED_HOSTS` | *(empty)* | Comma-separated public hostnames accepted in the `Host` header, e.g. `my-tunnel.trycloudflare.com`. Local hosts are always allowed. Anything else gets `421`, which protects the server against DNS-rebinding. `*` disables the check (not recommended). |
## Expose it with Cloudflare Tunnel
Install [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) (or drop `cloudflared.exe` next to the script; it is git-ignored).
**Windows, one click:** run `start_playlist_mcp.cmd`. It starts a free *quick tunnel*, reads its random `*.trycloudflare.com` hostname from the log, allows exactly that hostname, starts the server and prints the connector URL:
```text
Connector URL: https://random-words-here.trycloudflare.com/mcp
```
**Manually (any OS):**
```bash
cloudflared tunnel --url http://127.0.0.1:8000
# copy the https://<name>.trycloudflare.com hostname it prints, then in another terminal:
MCP_ALLOWED_HOSTS=<name>.trycloudflare.com python playlist_mcp.py
```
Quick tunnels get a new hostname on every start. For a stable URL, create a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/) on your own domain and set `MCP_ALLOWED_HOSTS=mcp.yourdomain.com` (the launcher then skips the quick tunnel and only starts the server).
## Connect to Claude
**claude.ai or Claude Desktop:** *Settings → Connectors → Add custom connector*, paste `https://<your-tunnel-host>/mcp`. Enable it in a chat and ask:
> Here's a playlist: https://www.youtube.com/playlist?list=... — list the videos, then read the transcripts of the first five and give me a one-paragraph summary of each.
**Claude Code** (no tunnel needed, same machine):
```bash
claude mcp add --transport http youtube-playlist http://127.0.0.1:8000/mcp
```
## Notes
- The server has **no authentication**: anyone who knows your tunnel URL can call these two read-only tools while it runs. Quick-tunnel URLs are random and short-lived; for a permanent setup, put the named tunnel behind [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/).
- Only public playlists and videos with captions (manual or auto-generated) work. YouTube may rate-limit transcript requests from some IPs.
## License
[MIT](LICENSE) © 2026 xoliddev