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

![yt2md web UI](docs/screenshot.png)

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

## Output example

```markdown
# 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)**

```bash
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**

```bash
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](https://docs.astral.sh/uv/), no install step: `uv run app/yt2md.py`.

## Documentation

The **[manual](docs/MANUAL.md)** 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](https://github.com/jdepoix/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](LICENSE)