YouTube Transcript MCP Server

Um servidor MCP de alto desempenho para buscar transcrições de vídeos do YouTube, com suporte para cache, limitação de taxa e rotação de proxy.

GitHub
4
Experimente este MCPPatrocinado

Documentação

YouTube Transcript MCP Server

Go Version License: MIT CI

Um servidor de alto desempenho do Model Context Protocol (MCP) para buscar transcrições de vídeos do YouTube, implementado em Go.

⚡ Início Rápido (Claude Code)

Instale o binário stdio e registre-o com o Claude Code em um único comando:

# 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

Para Claude Desktop, Cursor e configuração manual em JSON, consulte a seção Configuração de Cliente MCP abaixo.

🎬 Demonstração

GIF de demonstração em breve. Uma gravação curta de tela mostrando a busca de transcrições a partir de um cliente MCP será adicionada aqui.

📦 Registro e Distribuição MCP

  • Registros: Este servidor está sendo preparado para descoberta por meio de registros MCP, como o MCP Registry e o Smithery. O manifesto do registro é adicionado em um PR separado.
  • Binários pré-compilados e imagem Docker: Binários multiplataforma e uma imagem de contêiner serão publicados após a primeira release do GitHub ser marcada. Até lá, instale via go install (acima) ou compile a partir do código-fonte (consulte a seção Instalação abaixo).

🚀 Recursos

  • Compatível com o Protocolo MCP 2024-11-05: Implementação completa do Model Context Protocol
  • 5 Ferramentas Poderosas:
    • get_transcript: Busca a transcrição de um único vídeo
    • get_multiple_transcripts: Processa vários vídeos em lote
    • translate_transcript: Busca legendas no idioma especificado (incluindo legendas com tradução automática do YouTube quando disponíveis). Isso não traduz mecanicamente texto arbitrário.
    • format_transcript: Formata transcrições (texto simples, SRT, VTT, etc.)
    • list_available_languages: Lista os idiomas de legenda disponíveis
  • Alto Desempenho: Construído com Go para velocidade e eficiência
  • Cache: Cache em memória implementado (Redis é planejado/ainda não implementado; CACHE_TYPE=redis atualmente usa o cache em memória como fallback)
  • Limitação de Taxa: Proteção contra limites da API do YouTube
  • Suporte a Proxy: Rotação entre vários proxies
  • Pronto para Docker: Implantação fácil com Docker Compose
  • Monitoramento: Verificações de saúde integradas (métricas do Prometheus são planejadas/ainda não implementadas)

📋 Requisitos

  • Go 1.24 ou superior
  • Docker e Docker Compose (opcional)
  • Conexão com a internet

🎯 Configuração de Cliente MCP

Instalação Rápida (Recomendada)

Use o script de instalação automática:

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

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

O instalador irá:

  • Compilar o binário do servidor MCP
  • Configurar o Claude Desktop automaticamente
  • Configurar variáveis de ambiente

Instalar via Go Install

Você pode instalar o servidor MCP diretamente usando 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

Em seguida, configure seu cliente MCP para usar o binário instalado:

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

Nota: Se você instalou em $GOPATH/bin, certifique-se de que ele esteja no seu PATH, ou use o caminho completo no campo de comando.

Configuração Manual

Claude Desktop

Para usar este servidor com o Claude Desktop, adicione ao seu 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"
      }
    }
  }
}

Importante: O Claude Desktop requer a versão stdio do servidor (youtube-mcp-stdio), não o servidor HTTP.

Compile o servidor stdio:

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

Claude Code (claude.ai/code)

Uma vez que youtube-mcp-stdio esteja no seu PATH (consulte Instalar via Go Install), registre-o com um único comando:

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

Você também pode apontar o Claude Code para um caminho de binário explícito e passar variáveis de ambiente:

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

Cursor

O Cursor suporta servidores MCP por meio de suas configurações. Para configurar:

  1. Abra as Configurações do Cursor (Cmd+, no macOS, Ctrl+, no Windows/Linux)
  2. Pesquise por "MCP" ou "Model Context Protocol"
  3. Adicione a configuração do servidor:
{
  "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"
      }
    }
  }
}

Consulte docs/mcp-client-setup.md para instruções detalhadas de configuração.

🛠️ Instalação

Usando 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

Usando 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

⚙️ Configuração

Copie .env.example para .env e configure:

cp .env.example .env

Principais opções de configuração:

  • PORT: Porta do servidor (padrão: 8080)
  • YOUTUBE_DEFAULT_LANGUAGES: Idiomas padrão para transcrições
  • CACHE_TYPE: Tipo de cache (memory/redis)
  • SECURITY_ENABLE_AUTH: Ativar autenticação da API
  • LOG_LEVEL: Nível de registro (debug/info/warn/error)

🔧 Uso

Usando com Clientes MCP (Claude Desktop, Cursor, etc.)

O servidor MCP será iniciado automaticamente pelo seu cliente MCP. Uma vez configurado, você pode usar as ferramentas diretamente em suas conversas.

Usando como Servidor HTTP

Para desenvolvimento ou testes, você também pode executar a versão do servidor HTTP:

# Run HTTP server
make run

Em seguida, teste com:

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

Listar Ferramentas Disponíveis

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

Obter Transcrição

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

Obter Múltiplas Transcrições

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

🧪 Desenvolvimento

Executando Testes

# Run all tests
make test

# Run with coverage
make test-coverage

# Run benchmarks
make benchmark

Qualidade de Código

# Format code
make fmt

# Run linter
make lint

# Security scan
make security

Desenvolvimento com Recarga Automática

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

# Run with hot reload
make dev

🐳 Implantação com Docker

Implantação Básica

# Build and start
make up-build

# View logs
make logs

# Stop services
make down

Com Cache Redis

# Start with Redis
make up-redis

Com Monitoramento

# Start with Prometheus & Grafana
make up-monitoring

📊 Monitoramento

Verificação de Saúde

curl http://localhost:8080/health

Verificação de Prontidão

curl http://localhost:8080/ready

Métricas

Nota: Métricas do Prometheus são planejadas/ainda não implementadas. O endpoint /metrics atualmente retorna um placeholder (# TODO: Implement Prometheus metrics) junto com estatísticas básicas de requisições.

curl http://localhost:9090/metrics

🐛 Solução de Problemas

Problemas Comuns

Erro "Empty transcript response"

  • Causa: O servidor está rodando em modo HTTP em vez de modo stdio
  • Solução: Certifique-se de usar o binário youtube-mcp-stdio, não o youtube-transcript-mcp

Erro "Request timed out"

  • Causa: Timeout do Claude Desktop ou servidor não respondendo
  • Solução:
    • Reinicie o Claude Desktop
    • Verifique os logs do servidor: LOG_LEVEL=debug no ambiente
    • Verifique a conectividade de rede

"Failed to extract player response" nas verificações de saúde

  • Causa: Mudanças na estrutura da página do YouTube ou limitação de taxa
  • Solução: Isso geralmente é temporário. O servidor tentará novamente automaticamente.

Servidor não conectando ao Claude Desktop

  • Causa: Configuração incorreta ou caminho do binário errado
  • Solução:
    1. Verifique se o binário existe: ls -la /path/to/youtube-mcp-stdio
    2. Verifique os logs do Claude Desktop: Developer → Open logs
    3. Certifique-se de que o arquivo de configuração é JSON válido

Modo de Depuração

Ative o registro de depuração para ver informações detalhadas:

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

🔒 Segurança

  • Autenticação por Chave de API: Defina SECURITY_ENABLE_AUTH=true e configure as chaves de API
  • Limitação de Taxa: Limitação de taxa configurável por IP
  • Lista de Permissões/Bloqueios por IP: Controle o acesso por endereço IP
  • CORS: Políticas CORS configuráveis

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie seu branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  4. Envie para o branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

📝 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

⚠️ Aviso Legal

Esta ferramenta é para fins educacionais e de pesquisa. Por favor, respeite os Termos de Serviço do YouTube e as leis de direitos autorais ao usar transcrições.