YouTube Transcript MCP Server

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

🎬 Demo

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

📦 MCP Registry & Distribution

• Registries: This server is being prepared for discovery via MCP registries such as the MCP Registry and Smithery. 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 via go install (above) or build from source (see the Installation section below).

🚀 Features

• 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: Fetch captions in the specified language (including YouTube's auto-translated captions when available). This does not machine-translate arbitrary text.
  • 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 cache implemented (Redis is planned/not yet implemented; CACHE_TYPE=redis currently falls back to the memory cache)
• 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 (Prometheus metrics are planned/not yet implemented)

🧪 Development

Running Tests

# Run all tests
make test

# Run with coverage
make test-coverage

# Run benchmarks
make benchmark

Code Quality

# Format code
make fmt

# Run linter
make lint

# Security scan
make security

Hot Reload Development

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

# Run with hot reload
make dev

📊 Monitoring

Health Check

curl http://localhost:8080/health

Readiness Check

curl http://localhost:8080/ready

Metrics

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

curl http://localhost:9090/metrics

🔒 Security

• 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

🤝 Contributing

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

📝 License

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

🙏 Acknowledgments

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

⚠️ Disclaimer

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

⚡ Quick Start (Claude Code)

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 the MCP Client Setup section below.

📋 Requirements

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

🎯 MCP Client Setup

Quick Install (Recommended)

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

Install via Go Install

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.

Manual Setup

Claude Desktop

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 (claude.ai/code)

Once youtube-mcp-stdio is on your PATH (see Install via Go Install), register it with a single command:

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

You can also point Claude Code at an explicit binary path and pass environment variables:

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

Cursor

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.

🛠️ Installation

Using Go

# 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

Using Docker

# 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

⚙️ Configuration

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)

🔧 Usage

Using with MCP Clients (Claude Desktop, Cursor, etc.)

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

Using as HTTP Server

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

List Available Tools

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

Get Transcript

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
      }
    }
  }'

Get Multiple Transcripts

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
      }
    }
  }'

🐳 Docker Deployment

Basic Deployment

# Build and start
make up-build

# View logs
make logs

# Stop services
make down

With Redis Cache

# Start with Redis
make up-redis

With Monitoring

# Start with Prometheus & Grafana
make up-monitoring

🐛 Troubleshooting

Common Issues

"Empty transcript response" error

• 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

"Request timed out" error

• Cause: Claude Desktop timeout or server not responding
• Solution:
  • Restart Claude Desktop
  • Check server logs: LOG_LEVEL=debug in 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.

Server not connecting to Claude Desktop

• 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

Debug Mode

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