YouTube Transcript MCP Server
A production-ready Model Context Protocol (MCP) server that provides YouTube transcript fetching capabilities using yt-dlp CLI for reliable subtitle extraction. Uses browser impersonation and a JS runtime to reduce YouTube rate limiting.
Status: Production Ready
- CLI-Based: Uses yt-dlp subprocess with browser impersonation to reduce HTTP 429 rate limiting
- FastMCP 2.14.5: Tool annotations, context logging, progress reporting, prompt templates
- GHCR CI/CD: Multi-arch Docker images (amd64/arm64) built on every push
- Universal Compatibility: Time parameters work across all MCP clients
- Advanced Analytics: Enhanced transcript summary with content analysis
Features
- Fetch transcripts from YouTube videos with metadata and timestamps
- Time filtering - extract specific segments by start/end times
- Search functionality - find text within transcripts with context
- Advanced analytics - speaking pace, filler words, engagement metrics, top words
- Language detection - list available transcript languages
- Prompt templates - pre-built prompts for video summarization and topic search
- Transcript caching - 10-minute TTL cache avoids redundant YouTube requests
- Retry with backoff - automatic retries on timeouts and transient errors
- Universal format support - handles both video IDs and full YouTube URLs
- Dual transport - STDIO and HTTP transport modes
- Docker support - containerized deployment via GHCR with health checks
Installation
Docker (Recommended)```bash
Pull from GHCR and run
docker run -d -p 8080:8080 ghcr.io/suckerfish/yttranscript_mcp:latest
Or use docker compose
docker compose up -d
Health check
curl http://localhost:8080/health
### Local Development```bash
# Install dependencies
uv pip install -e .
# Run server (STDIO mode)
python src/server.py
# Run server (HTTP mode)
uvicorn src.server:app --host 0.0.0.0 --port 8080
Usage
Available Tools
All tools are read-only (readOnlyHint=True) and tagged read.
- get_transcript - Fetch video transcripts with optional time filtering
- search_transcript - Search for specific text within transcripts
- get_transcript_summary - Advanced analytics and content insights
- get_available_languages - List available transcript languages
Prompt Templates
- summarize_video(video_id, language_code) - Summarize a YouTube video transcript
- search_topic_in_video(video_id, topic) - Search for and analyze a topic within a video
Testing Commands```bash
Discover tools
mcp tools .venv/bin/python src/server.py
Basic transcript
mcp call get_transcript --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py
Time-filtered transcript
mcp call get_transcript --params '{"video_id":"jNQXAC9IVRw", "start_time": 10, "end_time": 60}' .venv/bin/python src/server.py
Search within transcript
mcp call search_transcript --params '{"video_id":"jNQXAC9IVRw", "query":"example"}' .venv/bin/python src/server.py
Advanced analytics
mcp call get_transcript_summary --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py
Available languages
mcp call get_available_languages --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py
## MCP Client Configuration
### HTTP Transport (Production)```json
{
"yttranscript": {
"url": "http://localhost:8080/mcp"
}
}
STDIO Transport (Development)```json
{
"yttranscript": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/yttranscript_mcp",
"src/server.py"
]
}
}
## Key Features
### Universal Parameter Compatibility
Time filtering parameters accept multiple formats:
- Integers: `{"start_time": 10}`
- Floats: `{"start_time": 10.5}`
- Strings: `{"start_time": "10"}`
- Nulls: `{"start_time": null}` or `{"start_time": "null"}`
### Advanced Analytics
The `get_transcript_summary` tool provides:
- **Speaking pace analysis** (words per minute with descriptive labels)
- **Filler word detection** (um, uh, like, etc.) with percentages
- **Content indicators** (conversational, formal, high energy)
- **Top frequent words** (excluding stop words)
- **Engagement metrics** (questions, exclamations)
- **Reading time estimates** at multiple speeds
### CLI Implementation Benefits
- **Fewer rate limits** - browser impersonation, a JS runtime, and backoff retries on HTTP 429
- **Reliable extraction** - uses yt-dlp's robust parsing
- **Automatic retries** - backoff on timeouts and transient errors
- **Format flexibility** - handles VTT, JSON3, and other subtitle formats
## Configuration
### Environment Variables```bash
YT_TRANSCRIPT_SERVER_PORT=8080 # Server port (default: 8080)
YT_TRANSCRIPT_SERVER_HOST=0.0.0.0 # Server host (default: 0.0.0.0)
YT_TRANSCRIPT_DEBUG=false # Debug mode
Dependencies
- fastmcp>=2.14.5,<3.0.0 - MCP server framework
- yt-dlp - YouTube transcript extraction via CLI
- pydantic>=2.0.0 - Data validation and models
- uvicorn>=0.24.0 - ASGI server for HTTP transport
This project uses uv for package management.
Deployment
Docker images are built by GitHub Actions on every push to main and published to GHCR:ghcr.io/suckerfish/yttranscript_mcp:latest
Multi-arch support: linux/amd64 and linux/arm64.
Troubleshooting
- Tool not found: Verify
@mcp.tool()decorator in tool definitions - Validation errors: Video IDs must be 11 characters, time values must be non-negative
- Time filtering issues: Parameters accept multiple formats (int/float/string/null)
- Transport issues: Use
uvicornfor HTTP mode,python src/server.pyfor STDIO - No transcript available: Check with
get_available_languagesfirst - Missing session ID: Server uses
stateless_http=Truefor clients without session management
License
This project is open source and available under the MIT License.