YouTube Transcript MCP Server

Un servidor MCP de alto rendimiento para obtener transcripciones de videos de YouTube, con soporte para almacenamiento en caché, limitación de velocidad y rotación de proxies.

GitHub
4
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Transcripciones de YouTube

Go Version License: MIT CI

Un servidor de Protocolo de Contexto de Modelo (MCP) de alto rendimiento para obtener transcripciones de videos de YouTube, implementado en Go.

⚡ Inicio Rápido (Claude Code)

Instale el binario stdio y luego regístrelo con Claude Code en un solo 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 y configuración manual JSON, consulte la sección Configuración de Cliente MCP a continuación.

🎬 Demo

El GIF de demostración estará disponible próximamente. Se añadirá aquí una breve grabación de pantalla que muestre la obtención de transcripciones desde un cliente MCP.

📦 Registro y Distribución MCP

  • Registros: Este servidor se está preparando para su descubrimiento a través de registros MCP como el Registro MCP y Smithery. El manifiesto del registro se añade en una solicitud de extracción separada.
  • Binarios precompilados e imagen Docker: Se publicarán binarios multiplataforma y una imagen de contenedor después de etiquetar la primera versión de GitHub. Hasta entonces, instale mediante go install (arriba) o compile desde el código fuente (consulte la sección Instalación a continuación).

🚀 Características

  • Cumplimiento del Protocolo MCP 2024-11-05: Implementación completa del Protocolo de Contexto de Modelo
  • 5 Herramientas Potentes:
    • get_transcript: Obtener transcripción de un solo video
    • get_multiple_transcripts: Procesar múltiples videos por lotes
    • translate_transcript: Obtener subtítulos en el idioma especificado (incluidos los subtítulos traducidos automáticamente de YouTube cuando estén disponibles). Esto no traduce automáticamente texto arbitrario.
    • format_transcript: Formatear transcripciones (texto plano, SRT, VTT, etc.)
    • list_available_languages: Listar idiomas de subtítulos disponibles
  • Alto Rendimiento: Construido con Go para velocidad y eficiencia
  • Almacenamiento en Caché: Caché en memoria implementada (Redis está planificado/aún no implementado; CACHE_TYPE=redis actualmente recurre a la caché en memoria)
  • Limitación de Velocidad: Protección contra los límites de la API de YouTube
  • Soporte de Proxy: Rotación a través de múltiples proxies
  • Listo para Docker: Implementación fácil con Docker Compose
  • Monitoreo: Verificaciones de salud integradas (las métricas de Prometheus están planificadas/aún no implementadas)

📋 Requisitos

  • Go 1.24 o superior
  • Docker y Docker Compose (opcional)
  • Conexión a Internet

🎯 Configuración de Cliente MCP

Instalación Rápida (Recomendada)

Use el script de instalación automática:

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

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

El instalador:

  • Compilará el binario del servidor MCP
  • Configurará Claude Desktop automáticamente
  • Configurará las variables de entorno

Instalar mediante Go Install

Puede instalar el servidor MCP directamente 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

Luego configure su cliente MCP para usar el binario instalado:

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

Nota: Si instaló en $GOPATH/bin, asegúrese de que esté en su PATH, o use la ruta completa en el campo de comando.

Configuración Manual

Claude Desktop

Para usar este servidor con Claude Desktop, agregue a su 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: Claude Desktop requiere la versión stdio del servidor (youtube-mcp-stdio), no el servidor HTTP.

Compile el servidor stdio:

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

Claude Code (claude.ai/code)

Una vez que youtube-mcp-stdio esté en su PATH (consulte Instalar mediante Go Install), regístrelo con un solo comando:

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

También puede apuntar Claude Code a una ruta binaria explícita y pasar variables de entorno:

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

Cursor

Cursor admite servidores MCP a través de su configuración. Para configurarlo:

  1. Abra la Configuración de Cursor (Cmd+, en macOS, Ctrl+, en Windows/Linux)
  2. Busque "MCP" o "Protocolo de Contexto de Modelo"
  3. Agregue la configuración del 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 obtener instrucciones detalladas de configuración.

🛠️ Instalación

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

⚙️ Configuración

Copie .env.example a .env y configure:

cp .env.example .env

Opciones de configuración clave:

  • PORT: Puerto del servidor (predeterminado: 8080)
  • YOUTUBE_DEFAULT_LANGUAGES: Idiomas predeterminados para transcripciones
  • CACHE_TYPE: Tipo de caché (memoria/redis)
  • SECURITY_ENABLE_AUTH: Habilitar autenticación de API
  • LOG_LEVEL: Nivel de registro (depuración/información/advertencia/error)

🔧 Uso

Uso con Clientes MCP (Claude Desktop, Cursor, etc.)

El servidor MCP se iniciará automáticamente mediante su cliente MCP. Una vez configurado, puede usar las herramientas directamente en sus conversaciones.

Uso como Servidor HTTP

Para desarrollo o pruebas, también puede ejecutar la versión del servidor HTTP:

# Run HTTP server
make run

Luego pruebe con:

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

Listar Herramientas Disponibles

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

Obtener Transcripción

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

Obtener Múltiples Transcripciones

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

🧪 Desarrollo

Ejecutar Pruebas

# Run all tests
make test

# Run with coverage
make test-coverage

# Run benchmarks
make benchmark

Calidad del Código

# Format code
make fmt

# Run linter
make lint

# Security scan
make security

Desarrollo con Recarga Automática

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

# Run with hot reload
make dev

🐳 Implementación con Docker

Implementación Básica

# Build and start
make up-build

# View logs
make logs

# Stop services
make down

Con Caché Redis

# Start with Redis
make up-redis

Con Monitoreo

# Start with Prometheus & Grafana
make up-monitoring

📊 Monitoreo

Verificación de Salud

curl http://localhost:8080/health

Verificación de Preparación

curl http://localhost:8080/ready

Métricas

Nota: Las métricas de Prometheus están planificadas/aún no implementadas. El endpoint /metrics actualmente devuelve un marcador de posición (# TODO: Implement Prometheus metrics) junto con estadísticas básicas de solicitudes.

curl http://localhost:9090/metrics

🐛 Solución de Problemas

Problemas Comunes

Error de "respuesta de transcripción vacía"

  • Causa: El servidor se está ejecutando en modo HTTP en lugar de modo stdio
  • Solución: Asegúrese de usar el binario youtube-mcp-stdio, no youtube-transcript-mcp

Error de "tiempo de espera de solicitud agotado"

  • Causa: Tiempo de espera de Claude Desktop o servidor que no responde
  • Solución:
    • Reinicie Claude Desktop
    • Verifique los registros del servidor: LOG_LEVEL=debug en el entorno
    • Verifique la conectividad de red

"No se pudo extraer la respuesta del reproductor" en las verificaciones de salud

  • Causa: Cambios en la estructura de la página de YouTube o limitación de velocidad
  • Solución: Esto suele ser temporal. El servidor reintentará automáticamente.

El servidor no se conecta a Claude Desktop

  • Causa: Configuración incorrecta o ruta binaria incorrecta
  • Solución:
    1. Verifique que el binario exista: ls -la /path/to/youtube-mcp-stdio
    2. Verifique los registros de Claude Desktop: Desarrollador → Abrir registros
    3. Asegúrese de que el archivo de configuración sea JSON válido

Modo de Depuración

Habilite el registro de depuración para ver información detallada:

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

🔒 Seguridad

  • Autenticación con Clave de API: Configure SECURITY_ENABLE_AUTH=true y configure las claves de API
  • Limitación de Velocidad: Limitación de velocidad configurable por IP
  • Lista Blanca/Negra de IP: Controle el acceso por dirección IP
  • CORS: Políticas CORS configurables

🤝 Contribuciones

  1. Haga un fork del repositorio
  2. Cree su rama de características (git checkout -b feature/amazing-feature)
  3. Realice sus cambios (git commit -m 'Add amazing feature')
  4. Envíe a la rama (git push origin feature/amazing-feature)
  5. Abra una Solicitud de Extracción

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENCIA para obtener más detalles.

🙏 Agradecimientos

⚠️ Aviso Legal

Esta herramienta es para fines educativos y de investigación. Respete los Términos de Servicio de YouTube y las leyes de derechos de autor al usar transcripciones.