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

• MCP Protocol 2024-11-05 Compliant: Full implementation of the Model Context Protocol
• 5 Powerful Tools:
  • get_transcript: Fetch transcript for a single video
  • get_multiple_transcripts: Batch process multiple videos
  • translate_transcript: Translate transcripts to different languages
  • format_transcript: Format transcripts (plain text, SRT, VTT, etc.)
  • list_available_languages: List available subtitle languages
• High Performance: Built with Go for speed and efficiency
• Caching: In-memory and Redis cache support
• Rate Limiting: Protect against YouTube API limits
• Proxy Support: Rotate through multiple proxies
• Docker Ready: Easy deployment with Docker Compose
• Monitoring: Built-in health checks and metrics

• Go 1.24 or higher
• Docker & Docker Compose (optional)
• Internet connection

Use the automatic installation script:

# Clone the repository
git clone https://github.com/kyong0612/youtube-mcp.git
cd youtube-mcp

# Run the installer
./scripts/install-mcp.sh

The installer will:

• Build the MCP server binary
• Configure Claude Desktop automatically
• Set up environment variables

You can install the MCP server directly using go install:

# 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

Then configure your MCP client to use the installed binary:

{
  "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 your claude_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.

Build the stdio server:

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

Claude Code automatically detects MCP servers. Use the same configuration as Claude Desktop.

Cursor supports MCP servers through its settings. To configure:

1. Open Cursor Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux)
2. Search for "MCP" or "Model Context Protocol"
3. Add the server configuration:

{
  "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"
      }
    }
  }
}

See docs/mcp-client-setup.md for 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

Copy .env.example to .env and configure:

cp .env.example .env

Key configuration options:

• PORT: Server port (default: 8080)
• YOUTUBE_DEFAULT_LANGUAGES: Default languages for transcripts
• CACHE_TYPE: Cache type (memory/redis)
• SECURITY_ENABLE_AUTH: Enable API authentication
• LOG_LEVEL: Logging level (debug/info/warn/error)

The MCP server will be automatically started by your MCP client. Once configured, you can use the tools directly in your conversations.

For development or testing, you can also run the HTTP server version:

# Run HTTP server
make run

Then test with:

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 Redis
make up-redis

# Start with Prometheus & Grafana
make up-monitoring

curl http://localhost:8080/health

curl http://localhost:8080/ready

curl http://localhost:9090/metrics

• Cause: The server is running in HTTP mode instead of stdio mode
• Solution: Ensure you're using youtube-mcp-stdio binary, not youtube-transcript-mcp

• Cause: Claude Desktop timeout or server not responding
• Solution:
  • Restart Claude Desktop
  • Check server logs: LOG_LEVEL=debug in environment
  • Verify network connectivity

• 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:
  1. Verify the binary exists: ls -la /path/to/youtube-mcp-stdio
  2. Check Claude Desktop logs: Developer → Open logs
  3. 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: Set SECURITY_ENABLE_AUTH=true and configure API keys
• Rate Limiting: Configurable per-IP rate limiting
• IP Whitelisting/Blacklisting: Control access by IP address
• CORS: Configurable CORS policies

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

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

• Inspired by youtube-transcript-api
• Built for the Model Context Protocol

This tool is for educational and research purposes. Please respect YouTube's Terms of Service and copyright laws when using transcripts.