yt2md

YouTube transcripts to Markdown. Self-hosted, with a web UI, a CLI and an MCP server for Claude.

Paste one or many YouTube links, get clean .md files: title, channel, language, and the transcript grouped into readable paragraphs with clickable timestamps. Optionally connect it to Claude, so you can just say "get the transcript of this video and summarize it".

Features

• Web UI: paste links, see progress per video, download single files, all files, or one merged file

• CLI: yt2md.py <url> <url> or -f links.txt, with --merge and --plain

• MCP server: three tools for Claude (get_transcript, list_transcripts, read_transcript)

• Readable Markdown: ~60 s paragraphs, [mm:ss] links that jump into the video

• Language preference: e.g. de,en, falls back to any available transcript

• Docker ready: one image, two services, runs on amd64 and arm64 (Raspberry Pi)

• No API key needed

Related MCP server: YouTube Transcript Remote MCP Server

Output example

# How To Start With MES

- **Channel:** Some Channel
- **URL:** https://www.youtube.com/watch?v=9x0VMukDjhw
- **Transcript:** English (auto-generated)
- **Fetched:** 2026-09-18

---

**[00:00](https://www.youtube.com/watch?v=9x0VMukDjhw&t=0s)** Manufacturing execution systems. Where do I start? ...

**[01:02](https://www.youtube.com/watch?v=9x0VMukDjhw&t=62s)** The first thing you need to understand is ...

Quick start

Docker (recommended)

git clone https://github.com/echtelerp/yt2md.git
cd yt2md
cp .env.example .env          # set YT2MD_MCP_SECRET, see the manual
mkdir -p data
docker compose up -d --build

Open http://<host>:8765. Transcripts are saved to ./data.

Without Docker

pip install youtube-transcript-api
python app/yt2md.py                          # web UI, opens your browser
python app/yt2md.py https://youtu.be/xyz     # CLI

Or with uv, no install step: uv run app/yt2md.py.

Documentation

The manual covers everything step by step:

1. Installation with Docker or plain Python

2. Web UI and CLI usage

3. Reverse proxy setup (Nginx Proxy Manager and plain nginx)

4. Connecting Claude via MCP, including security

5. Updating, configuration reference, troubleshooting

Important: where it runs matters

YouTube blocks transcript requests from most cloud and datacenter IPs. yt2md works reliably on a residential connection (homelab, Raspberry Pi, your laptop). On a VPS you will likely see "IP blocked" errors.

Disclaimer

This project is not affiliated with YouTube, Google or Anthropic. It uses the unofficial youtube-transcript-api. Transcripts belong to their creators: use them for personal research and notes, respect copyright and YouTube's Terms of Service.

License

MIT