YouTube Transcript MCP Server

A high-performance MCP server for fetching YouTube video transcripts, with support for caching, rate limiting, and proxy rotation.

A high-performance Model Context Protocol (MCP) server for fetching YouTube video transcripts, implemented in Go.

Install the stdio binary, then register it with Claude Code in a single command:

# 1. Install the stdio binary (requires Go 1.24+) go install github.com/kyong0612/youtube-mcp/cmd/mcp@latest mv "$(go env GOPATH)/bin/mcp" "$(go env GOPATH)/bin/youtube-mcp-stdio" # 2. Register the server with Claude Code (one-liner) claude mcp add youtube-transcript -- youtube-mcp-stdio

For Claude Desktop, Cursor, and manual JSON configuration, see theMCP Client Setupsection below.

Demo GIF coming soon.A short screen recording showing transcript fetching from an MCP client will be added here.

- Registries: This server is being prepared for discovery via MCP registries such as theMCP RegistryandSmithery. The registry manifest is added in a separate PR.
- Prebuilt binaries & Docker image: Cross-platform binaries and a container image will be published after the first GitHub release is tagged. Until then, install viago install(above) or build from source (see theInstallationsection below).

# Clone the repository git clone https://github.com/kyong0612/youtube-mcp.git cd youtube-mcp # Run the installer ./scripts/install-mcp.sh

# Install the stdio version for MCP clients go install github.com/kyong0612/youtube-mcp/cmd/mcp@latest # The binary will be installed to $GOPATH/bin/mcp # Rename it for clarity mv $GOPATH/bin/mcp $GOPATH/bin/youtube-mcp-stdio # Or install to a specific location GOBIN=/usr/local/bin go install github.com/kyong0612/youtube-mcp/cmd/mcp@latest sudo mv /usr/local/bin/mcp /usr/local/bin/youtube-mcp-stdio

{ "mcpServers": { "youtube-transcript": { "command": "youtube-mcp-stdio", "args": [], "env": { "LOG_LEVEL": "info", "CACHE_ENABLED": "true", "YOUTUBE_DEFAULT_LANGUAGES": "en,ja" } } } }

Note: If you installed to$GOPATH/bin, make sure it's in your PATH, or use the full path in the command field.

To use this server with Claude Desktop, add to yourclaude_desktop_config.json:

{ "mcpServers": { "youtube-transcript": { "command": "/path/to/youtube-mcp/youtube-mcp-stdio", "args": [], "env": { "LOG_LEVEL": "info", "CACHE_ENABLED": "true", "YOUTUBE_DEFAULT_LANGUAGES": "en,ja" } } } }

Important: Claude Desktop requires the stdio version of the server (youtube-mcp-stdio), not the HTTP server.

go build -o youtube-mcp-stdio ./cmd/mcp/

Onceyoutube-mcp-stdiois on yourPATH(seeInstall via Go Install), register it with a single command:

claude mcp add youtube-transcript -- youtube-mcp-stdio

claude mcp add youtube-transcript \ --env YOUTUBE_DEFAULT_LANGUAGES=en,ja \ -- /path/to/youtube-mcp/youtube-mcp-stdio

{ "mcp.servers": { "youtube-transcript": { "command": "/path/to/youtube-mcp/youtube-mcp-stdio", "args": [], "env": { "LOG_LEVEL": "info", "CACHE_ENABLED": "true", "YOUTUBE_DEFAULT_LANGUAGES": "en,ja" } } } }

Seedocs/mcp-client-setup.mdfor detailed setup instructions.

# Clone the repository git clone https://github.com/kyong0612/youtube-mcp.git cd youtube-mcp # Install dependencies make deps # Build the application make build # Run the server make run

# Clone the repository git clone https://github.com/kyong0612/youtube-mcp.git cd youtube-mcp # Setup environment make env-setup # Edit .env file with your configuration # Start with Docker Compose make up

curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize" }'

curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_transcript", "arguments": { "video_identifier": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "languages": ["en", "ja"], "preserve_formatting": false } } }'

curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_multiple_transcripts", "arguments": { "video_identifiers": ["dQw4w9WgXcQ", "jNQXAC9IVRw"], "languages": ["en"], "continue_on_error": true } } }'

# Run all tests make test # Run with coverage make test-coverage # Run benchmarks make benchmark

# Format code make fmt # Run linter make lint # Security scan make security

# Install air for hot reload go install github.com/air-verse/air@latest # Run with hot reload make dev

# Build and start make up-build # View logs make logs # Stop services make down

# Start with Prometheus & Grafana make up-monitoring

Note: Prometheus metrics are planned/not yet implemented. The/metricsendpoint currently returns a placeholder (# TODO: Implement Prometheus metrics) along with basic request stats.

"Empty transcript response" error

- Cause: The server is running in HTTP mode instead of stdio mode
- Solution: Ensure you're usingyoutube-mcp-stdiobinary, notyoutube-transcript-mcp

- Cause: Claude Desktop timeout or server not responding
- Solution:

- Restart Claude Desktop
- Check server logs:LOG_LEVEL=debugin environment
- Verify network connectivity

"Failed to extract player response" in health checks

- Cause: YouTube page structure changes or rate limiting
- Solution: This is usually temporary. The server will retry automatically.

- Cause: Incorrect configuration or binary path
- Solution:
- Verify the binary exists:ls -la /path/to/youtube-mcp-stdio
- Check Claude Desktop logs: Developer → Open logs
- Ensure the config file is valid JSON

Enable debug logging to see detailed information:

{ "mcpServers": { "youtube-transcript": { "command": "/path/to/youtube-mcp/youtube-mcp-stdio", "args": [], "env": { "LOG_LEVEL": "debug", "CACHE_ENABLED": "true", "YOUTUBE_DEFAULT_LANGUAGES": "en,ja" } } } }

- API Key Authentication: SetSECURITY_ENABLE_AUTH=trueand configure API keys
- Rate Limiting: Configurable per-IP rate limiting
- IP Whitelisting/Blacklisting: Control access by IP address
- CORS: Configurable CORS policies
- Fork the repository
- Create your feature branch (git checkout -b feature/amazing-feature)
- Commit your changes (git commit -m 'Add amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

This project is licensed under the MIT License - see theLICENSEfile for details.

- Inspired byyoutube-transcript-api
- Built for theModel Context Protocol

🕷️ 9 MCP tools for web scraping, browser automation, vision, transcription and RAG query