YouTube Transcript MCP Server (Proxy Edition)

Proxy-aware MCP server for retrieving YouTube transcripts with built-in resilience features—residential proxy support, retry/backoff, throttling and caching. The server is compatible with Model Context Protocol clients such as n8n, Claude Desktop, Goose, LM Studio and more.

Key Features

• 🔁 Residential proxy support via YT_PROXY_HTTP / YT_PROXY_HTTPS or upstream corporate proxies.
• ♻️ Automatic retry & exponential backoff for IP bans and transient errors using tenacity.
• 💤 Rate limiting and jittered cooldowns to keep exit nodes healthy.
• 💾 Filesystem caching with a 14 day TTL to minimise repeated fetches.
• 📦 Ships as a Docker image and a single uvx command for zero-install usage.
• 🧰 MCP tools: get_transcript, get_timed_transcript, get_video_info with pagination (next_cursor) support.

Installation

[!TIP] Ensure uv is installed before using uvx.

uvx (recommended)

uvx --from git+https://github.com/<ORG>/mcp-youtube-transcript-proxy mcp-ytx --help

Replace <ORG> with your organisation or GitHub username if you forked this repository.

Docker

Build the container locally:

docker build -t mcp-ytx .

Run the server with proxy configuration:

docker run --rm -p 8088:8080 \
  -e YT_PROXY_HTTP="http://user:pass@res-proxy.example:8000" \
  -e YT_PROXY_HTTPS="http://user:pass@res-proxy.example:8000" \
  -e YT_MAX_RETRIES=6 -e YT_BACKOFF_MIN=2 -e YT_BACKOFF_MAX=60 \
  -e YT_SLEEP_BASE=3.0 -e YT_SLEEP_JITTER=1.5 \
  -e YT_RATE_LIMIT_REQUESTS=8 -e YT_RATE_LIMIT_PERIOD=60 \
  mcp-ytx serve

Docker Compose

services:
  mcp_ytx:
    build: .
    ports:
      - "8088:8080"
    environment:
      YT_PROXY_HTTP:  http://user:pass@res-proxy.example:8000
      YT_PROXY_HTTPS: http://user:pass@res-proxy.example:8000
      YT_CACHE_ENABLED: "1"
      YT_CACHE_TTL_SECONDS: "1209600"
      YT_RESPONSE_LIMIT: "50000"

Bring up the stack:

docker compose up --build

MCP Client Configuration

Claude Desktop / Goose / LM Studio

Add the following entry to your MCP configuration file:

{
  "mcpServers": {
    "youtube-transcript-proxy": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/<ORG>/mcp-youtube-transcript-proxy",
        "mcp-ytx",
        "serve"
      ]
    }
  }
}

n8n MCP Client Tool

Configure the MCP Tool node with the endpoint exposed by this server (default http://localhost:8080/mcp). n8n automatically discovers the get_transcript, get_timed_transcript, and get_video_info tools.

Environment Variables

Variable	Description
YT_PROXY_HTTP / YT_PROXY_HTTPS	Residential or corporate proxy URLs.
YT_COOKIES_PATH	Optional Netscape cookie jar path for authenticated sessions.
YT_MAX_RETRIES	Maximum retry attempts for blocked/failed requests (default: 6).
YT_BACKOFF_MIN / YT_BACKOFF_MAX	Exponential backoff range in seconds.
YT_SLEEP_BASE / YT_SLEEP_JITTER	Cooldown delay between fetches and jitter.
YT_RATE_LIMIT_REQUESTS / YT_RATE_LIMIT_PERIOD	Sliding window throttling configuration.
YT_CACHE_ENABLED	Enable/disable persistent caching (default: enabled).
YT_CACHE_TTL_SECONDS	Cache TTL in seconds (default: 14 days).
YT_CACHE_DIR	Override cache directory (default: ~/.cache/mcp-ytx).
YT_RESPONSE_LIMIT	Maximum characters per MCP response page (default: 50,000).
YT_PRESERVE_FORMATTING	Preserve YouTube formatting when available (true/false).
YT_USER_AGENT	Custom User-Agent header for YouTube page fetches.
YT_LISTEN_HOST / YT_LISTEN_PORT	Override the HTTP bind address (defaults: host 0.0.0.0, port 8080).

Usage Notes

• When YouTube blocks a proxy IP with RequestBlocked/IpBlocked, the server retries with exponential backoff. After exhausting retries it surfaces the error so you can rotate credentials.
• Cached responses automatically expire after their TTL. You can purge the cache manually by removing the directory defined in YT_CACHE_DIR.
• The transcript tools paginate responses via the next_cursor field. Continue fetching by passing the returned cursor in the subsequent request.
• For long-running operations the server sleeps between calls according to the configured cooldown/jitter parameters to protect residential proxies.

Development

Install dependencies with uv:

uv sync

Run the unit test suite:

uv run pytest

License

Released under the MIT License. See LICENSE.