yts — YouTube Transcript MCP Server

Minimal MCP server that downloads YouTube video transcripts via the yt-dlp CLI. Runs over stdio (for Claude Code / IDE integrations) or SSE (for Docker deploys and remote clients).

Tools

All success responses are dict. Failures surface as MCP protocol errors (isError: true), so clients see red error UI rather than a "success" wrapping a {"error": "..."} payload.

Related MCP server: youtube-mcp

Bypassing "This video is not available" / captcha errors

YouTube's bot detection rate-limits guest sessions to ~300 videos/hour per IP. When it triggers, yt-dlp masks the real reason as "This video is not available". The fix is authenticated cookies from a signed-in browser:

1. In your browser, sign in to YouTube.

2. Install a cookies-export extension (e.g. "Get cookies.txt LOCALLY" — Chrome/Firefox).

3. Export cookies for youtube.com — the extension gives you Netscape-format text.

4. Call set_cookies(cookies_text=<the exported text>) on the running server (via MCP Inspector, Claude Code, etc.).

5. All subsequent tool calls will run with --cookies injected automatically.

Cookies live only in the server process (chmod-600 tempfile). They do not survive docker compose restart — re-inject after each restart. Call clear_cookies() any time to drop them.

Requirements

• Python 3.10+

• yt-dlp on PATH (installed automatically by setup.sh inside the venv, or by the Docker image)

• ffmpeg — optional but recommended (handles subtitle format conversion)

• A JS runtime (node, deno, bun, or quickjs) — strongly recommended. YouTube protects many videos with a JS n challenge; without a runtime, yt-dlp masks the failure as "This video is not available". The Docker image installs nodejs by default. Locally, install one you already have (brew install node on macOS).

Quick start (Docker Compose)

Every push to main publishes a multi-arch image to Docker Hub: josetonyp/yts-mcp:latest (see the CI / published image section below). If you just want to run the server without building:

docker compose pull                     # fetch the pre-built image
docker compose up -d                    # start it
curl -N http://localhost:8765/sse       # verify the SSE endpoint responds
docker compose logs -f yts-mcp          # follow the yt-dlp trace log
docker compose down                     # stop & remove

To build locally from your working tree instead (dev flow):

docker compose up -d --build

Point at a different published tag (e.g. a specific commit) with the YTS_IMAGE env var:

YTS_IMAGE=josetonyp/yts-mcp:sha-abc1234 docker compose up -d

Then register with your MCP client:

{
  "mcpServers": {
    "yts": { "url": "http://127.0.0.1:8765/sse" }
  }
}

Docker CLI (no Compose)

If you don't want to use Compose, the same server runs via docker build + docker run:

# 1. Build the image (tag it 'yts-mcp' for convenience).
docker build -t yts-mcp .

# 2. Run it. --rm auto-removes on stop; -d detaches; -p publishes the SSE port.
docker run -d --rm \
  --name yts-mcp \
  -p 8765:8765 \
  yts-mcp

# 3. Verify.
curl -N http://localhost:8765/sse
docker logs -f yts-mcp                  # stream yt-dlp command log

Common variants

# Run in the foreground (Ctrl+C to stop) — useful for one-off debugging:
docker run --rm -p 8765:8765 yts-mcp

# Bind to a different host port:
docker run -d --rm --name yts-mcp -p 9000:8765 yts-mcp

# Tighter timeout (default is 120s per yt-dlp call):
docker run -d --rm --name yts-mcp -p 8765:8765 \
  -e YTDLP_TIMEOUT=60 \
  yts-mcp

# Verbose logs (adds yt-dlp stderr on successful calls):
docker run -d --rm --name yts-mcp -p 8765:8765 \
  -e YTS_LOG_LEVEL=DEBUG \
  yts-mcp

# Pin a specific yt-dlp release at build time:
docker build --build-arg YTDLP_VERSION=2025.09.05 -t yts-mcp:pinned .
docker run -d --rm --name yts-mcp -p 8765:8765 yts-mcp:pinned

# Stop, restart, remove:
docker stop yts-mcp
docker start yts-mcp
docker rm -f yts-mcp

Upgrading yt-dlp

YouTube changes their internals often; yt-dlp ships fixes weekly.

# With Compose:
docker compose build --no-cache --build-arg YTDLP_VERSION=latest
docker compose up -d

# With plain Docker CLI:
docker build --no-cache --build-arg YTDLP_VERSION=latest -t yts-mcp .
docker rm -f yts-mcp
docker run -d --rm --name yts-mcp -p 8765:8765 yts-mcp

Verify with the health tool from your MCP client, or:

docker exec yts-mcp yt-dlp --version

CI / published image

.github/workflows/docker.yml builds a multi-arch (amd64 + arm64) image and pushes it to Docker Hub.

Image URL: josetonyp/yts-mcp

Tags produced per push:

Triggers:

• Push to main/master → build and push

• Tag v* → build and push semver tags

• Pull request → build only (validates the Dockerfile), no push

• workflow_dispatch → manual runs from the Actions tab

First-time setup

1. Create a Docker Hub access token: https://hub.docker.com/settings/security → New Access Token → scope Read, Write, Delete. Copy it — shown once.

2. Create the repo on Docker Hub ahead of first push (recommended so it starts Public): https://hub.docker.com/repository/create → name yts-mcp → Public. Skipping this makes the first push auto-create it Private, and public consumers get denied errors.

3. Add two GitHub repository secrets: Settings → Secrets and variables → Actions → New repository secret.

   • DOCKERHUB_USERNAME = josetonyp

   • DOCKERHUB_TOKEN = the token from step 1

4. Init the repo and push to GitHub:

   git init && git add . && git commit -m "initial"
   git remote add origin git@github.com:<owner>/<repo>.git
   git push -u origin main

5. Wait ~3-5 min for the multi-arch build. Then:

   docker compose pull
   docker compose up -d

Environment variables

Pass these to docker run with -e VAR=value or set them in docker-compose.yml under environment:.

Local (stdio) setup

bash setup.sh

The script creates .venv/, installs mcp and yt-dlp, and prints an .mcp.json snippet like:

{
  "mcpServers": {
    "yts": {
      "type": "stdio",
      "command": "/absolute/path/to/yts/.venv/bin/python3",
      "args":    ["/absolute/path/to/yts/src/server.py"]
    }
  }
}

Local (SSE) dev mode

bash dev.sh                  # binds 127.0.0.1:8765
bash dev.sh --port 8888      # custom port

File layout

yts/
├── src/
│   ├── server.py                    ← FastMCP init, tool registration, composition root
│   ├── cookie_store.py              ← CookieStore + InvalidCookiesError (standalone)
│   └── transcript/                  ← yt-dlp adapter package — one class per file
│       ├── __init__.py              ← public API re-exports
│       ├── cue.py                   ← Cue (frozen dataclass)
│       ├── transcript.py            ← Transcript (dataclass + to_dict)
│       ├── video_info.py            ← VideoInfo (dataclass + from_yt_json)
│       ├── probe_videos.py          ← PROBE_VIDEOS list used by check_cookies
│       ├── ytdlp_client.py          ← YtDlpClient + 4 error classes
│       └── parsers/                 ← subtitle-format parsers
│           ├── __init__.py
│           └── vtt_parser.py        ← VttParser (WebVTT → cues, stateless)
├── .github/
│   └── workflows/
│       └── docker.yml               ← CI: build+push multi-arch image to GHCR
├── requirements.txt                 ← mcp + minimal HTTP deps
├── Dockerfile                       ← Python 3.12-slim + ffmpeg + nodejs + yt-dlp (pip)
├── docker-compose.yml               ← Uses Docker Hub image; falls back to local build
├── setup.sh                         ← Local venv + smoke test
├── dev.sh                           ← Launch SSE dev server
├── ARCHITECTURE.md                  ← Design decisions and layer contracts
└── README.md

See ARCHITECTURE.md for the design rationale.