YouTube Transcript MCP Server

A Docker-packaged MCP server that extracts transcripts from YouTube videos. Connect it to Claude Desktop, Claude Code, or any MCP-compatible client to let your AI read YouTube videos.

Features:

• Proxy support — residential proxy integration (Webshare or generic) to bypass YouTube's datacenter IP blocks
• SQLite caching — transcripts are cached locally for 7 days to avoid redundant fetches
• Rate limiting — built-in 1.5s delay between batch requests
• Dual transport — runs as SSE (default) or stdio

No YouTube API key required — uses YouTube's public transcript endpoints.

Quick Start

git clone https://github.com/sundog75/youtube-mcp-server.git
cd youtube-mcp-server

# Create your environment file
cp .env.example .env
# Edit .env — see "Proxy Setup" below

# Build and start
docker compose up -d

# Verify
curl http://localhost:8002/healthz

Proxy Setup

YouTube blocks most server and datacenter IPs from fetching transcripts. If you're running this on a VPS or cloud server, you'll need a residential proxy.

Option 1: No proxy (home network only)

If the server runs on your home internet connection, no proxy is needed:

YOUTUBE_PROXY_TYPE=none

Option 2: Webshare residential proxy (recommended)

Sign up at webshare.io for a paid residential plan (~$5.50/GB). The free tier uses datacenter IPs which YouTube also blocks.

YOUTUBE_PROXY_TYPE=webshare
WEBSHARE_PROXY_USERNAME=your_username
WEBSHARE_PROXY_PASSWORD=your_password

Option 3: Any HTTP proxy

YOUTUBE_PROXY_TYPE=generic
YOUTUBE_PROXY_URL=http://user:pass@proxy-host:port

Connect to Claude Desktop

Add this to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse", "http://localhost:8002/sse"]
    }
  }
}

Replace localhost with your server's IP if running remotely.

Connect to Claude Code

Add to your Claude Code MCP settings (.mcp.json or via the settings UI):

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse", "http://localhost:8002/sse"]
    }
  }
}

Available Tools

Tool	Description
get_transcript	Get the full transcript text from a video
get_transcript_json	Get transcript with metadata (video ID, language, cache status) as JSON
batch_transcripts	Get transcripts from multiple videos (comma-separated URLs)
search_transcript	Search for specific text within a video's transcript
transcript_health	Check proxy and cache health status

Example Usage

Once connected, ask your AI:

"Get the transcript from this YouTube video: https://www.youtube.com/watch?v=dQw4w9WgXcQ"

"Search for 'machine learning' in this video: https://www.youtube.com/watch?v=..."

"Get transcripts from these videos: VIDEO_ID_1, VIDEO_ID_2, VIDEO_ID_3"

Configuration

All configuration is via environment variables in .env:

Variable	Default	Description
YOUTUBE_PROXY_TYPE	none	Proxy type: none, webshare, or generic
WEBSHARE_PROXY_USERNAME	—	Webshare username (when type=webshare)
WEBSHARE_PROXY_PASSWORD	—	Webshare password (when type=webshare)
YOUTUBE_PROXY_URL	—	Full proxy URL (when type=generic)
YOUTUBE_PROXY_COUNTRY	—	ISO country code filter, comma-separated (webshare only)
YOUTUBE_PROXY_RETRIES	3	Retry count when proxy IP is blocked
MCP_HOST_PORT	8002	Host port to expose the server on
YT_CACHE_TTL_DAYS	7	Cache TTL in days

Maintenance

# View logs
docker logs -f youtube-mcp-server

# Rebuild with latest dependencies
docker compose build --no-cache && docker compose up -d

# Stop and remove
docker compose down

# Stop and remove including cached transcripts
docker compose down -v

Troubleshooting

"ip_blocked" errors

YouTube is blocking the server's IP. You need a residential proxy — see Proxy Setup.

Empty transcripts

Some videos don't have transcripts (auto-generated or manual). The tool will return a no_transcript error for these.

Container shows "unhealthy"

docker logs youtube-mcp-server

Check for Python import errors or port conflicts.

Claude Desktop can't connect

1. Check the server is running: curl http://localhost:8002/healthz
2. Make sure npx is available (Node.js must be installed on the Claude Desktop machine)
3. Check the URL in your MCP config matches the server's host and port

How It Works

Claude Desktop / Claude Code
    |
    v
supergateway (local, spawned by MCP client)
    | SSE/HTTP
    v
youtube-mcp-server (Docker container, port 8002)
    | python youtube_transcript_api
    v
YouTube (via residential proxy if configured)
    |
    v
Transcript text returned to AI

The server uses youtube-transcript-api to fetch transcripts from YouTube's public endpoints. Results are cached in a SQLite database inside a Docker volume (yt_mcp_cache) so repeated requests for the same video are instant.

Security

• No API keys required for YouTube access
• Proxy credentials stay in .env (gitignored, never committed)
• Container runs as non-root user (appuser, UID 1001)
• Resource-limited (512MB RAM, 0.5 CPU)
• Port binds to all interfaces by default — to restrict to localhost, set MCP_HOST_PORT=127.0.0.1:8002 in .env

License

MIT