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_HTTPSor
upstream corporate proxies. - ♻️ Automatic retry & exponential backoff for IP bans and transient errors
usingtenacity. - 💤 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
uvxcommand for zero-install
usage. - 🧰 MCP tools:
get_transcript,get_timed_transcript,get_video_infowith
pagination (next_cursor) support.
Installation
> [!TIP]
> Ensure uv is installed before using uvx.
uvx (recommended)```bash
uvx --from git+https://github.com/<ORG>/mcp-youtube-transcript-proxy mcp-ytx --help
Replace `` with your organisation or GitHub username if you forked this
repository.
### Docker
Build the container locally:```bash
docker build -t mcp-ytx .
Run the server with proxy configuration:```bash
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```yaml
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:```bash
docker compose up --build
## MCP Client Configuration
### Claude Desktop / Goose / LM Studio
Add the following entry to your MCP configuration file:```json
{
"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 inYT_CACHE_DIR. - The transcript tools paginate responses via the
next_cursorfield. 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:```bash
uv sync
Run the unit test suite:```bash
uv run pytest
License
Released under the MIT License. See LICENSE.
