MCP YouTube Extract

Extrai informações de vídeos e canais do YouTube usando a YouTube Data API.

GitHub
19
Experimente este MCPPatrocinado

Documentação

MCP YouTube Extract

PyPI version Python 3.13+ License: MIT Code style: black

Um servidor Model Context Protocol (MCP) para operações com YouTube, demonstrando conceitos essenciais do MCP, incluindo ferramentas e registro de logs.

✨ Sem necessidade de chave de API! Funciona imediatamente usando yt-info-extract para metadados de vídeo e yt-ts-extract para transcrições.

Recursos

  • Servidor MCP: Um servidor MCP totalmente funcional com:
    • Ferramentas: Extrai informações de vídeos do YouTube, incluindo metadados e transcrições
    • Registro de Logs Abrangente: Logs detalhados em toda a aplicação
    • Tratamento de Erros: Tratamento robusto de erros com lógica de fallback para transcrições
  • Integração com YouTube: Capacidades integradas de YouTube usando yt-info-extract e yt-ts-extract:
    • Extrai informações do vídeo (título, descrição, canal, data de publicação, contagem de visualizações)
    • Obtém transcrições de vídeo com lógica de fallback inteligente
    • Suporte para transcrições criadas manualmente e geradas automaticamente
    • Sem necessidade de chave de API para funcionalidade básica

📦 Disponível no PyPI

Este pacote agora está disponível no PyPI! Você pode instalá-lo diretamente com:

pip install mcp-youtube-extract

Visite a página do pacote: mcp-youtube-extract no PyPI

Instalação

Início Rápido (Recomendado)

A maneira mais fácil de começar é instalar a partir do PyPI:

pip install mcp-youtube-extract

Ou usando pipx (recomendado para ferramentas de linha de comando):

pipx install mcp-youtube-extract

Isso instalará a versão mais recente com todas as dependências. Você pode então executar o servidor MCP diretamente:

mcp_youtube_extract

Usando uv (Desenvolvimento)

Para desenvolvimento ou se você preferir uv:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install the project
git clone https://github.com/sinjab/mcp_youtube_extract.git
cd mcp_youtube_extract

# Install dependencies (including dev dependencies)
uv sync --dev

# Set up your API key for development
cp .env.example .env
# Edit .env and add your YouTube API key

A partir do código-fonte

  1. Clone o repositório:

    git clone https://github.com/sinjab/mcp_youtube_extract.git
cd mcp_youtube_extract

  2. Instale em modo de desenvolvimento:

    uv sync --dev

Configuração

Variáveis de Ambiente

Nenhuma configuração necessária! O servidor funciona imediatamente usando yt-info-extract para extração de metadados.

Opcional: Para funcionalidade aprimorada, você pode opcionalmente definir uma chave de API do YouTube:

# Optional YouTube API Configuration
YOUTUBE_API_KEY=your_youtube_api_key_here

Opcional:

  • YOUTUBE_API_KEY: Sua chave da API YouTube Data (opcional, fornece fallback adicional para extração de metadados)

Obtendo Sua Chave de API do YouTube (Opcional)

Embora não seja necessária, você pode opcionalmente configurar uma chave da API YouTube Data para funcionalidade aprimorada. Veja como obter uma:

Passo 1: Crie um Projeto no Google Cloud

  1. Vá para o Console do Google Cloud
  2. Clique em "Selecionar um projeto" no topo da página
  3. Clique em "Novo Projeto" e dê um nome (ex.: "MCP YouTube Extract")
  4. Clique em "Criar"

Passo 2: Ative a API YouTube Data

  1. No seu novo projeto, vá para a Biblioteca de APIs
  2. Pesquise por "YouTube Data API v3"
  3. Clique nela e depois clique em "Ativar"

Passo 3: Crie Credenciais de API

  1. Vá para a página de Credenciais
  2. Clique em "Criar Credenciais" e selecione "Chave de API"
  3. Sua nova chave de API será exibida - copie-a imediatamente
  4. Clique em "Restringir Chave" para protegê-la (recomendado)

Passo 4: Restrinja Sua Chave de API (Recomendado)

  1. Nas configurações da chave de API, clique em "Restringir Chave"
  2. Em "Restrições de API", selecione "Restringir chave"
  3. Escolha "YouTube Data API v3" no menu suspenso
  4. Clique em "Salvar"

Passo 5: Configure o Faturamento (Obrigatório)

  1. Vá para a página de Faturamento
  2. Vincule uma conta de faturamento ao seu projeto
  3. Nota: A API YouTube Data tem um nível gratuito de 10.000 unidades por dia, que geralmente é suficiente para a maioria dos casos de uso

Limites de Uso da Chave de API

  • Nível Gratuito: 10.000 unidades por dia
  • Custo: US$ 5 por 1.000 unidades após o nível gratuito
  • Nota: A chave de API é usada apenas como fallback quando yt-info-extract falha
  • A maioria dos usuários não precisará de uma chave de API, pois yt-info-extract lida com a maioria das solicitações

Melhores Práticas de Segurança

  • Nunca envie sua chave de API para o controle de versão
  • Use variáveis de ambiente conforme mostrado na seção de configuração
  • Restrinja sua chave de API apenas à API YouTube Data
  • Monitore o uso no Console do Google Cloud

Uso

Executando o Servidor MCP

Usando Instalação via PyPI (Recomendado)

# Install from PyPI
pip install mcp-youtube-extract

# Run the server
mcp_youtube_extract

Usando Configuração de Desenvolvimento

# Using uv
uv run mcp_youtube_extract

# Or directly
python -m mcp_youtube_extract.server

Executando Testes

# Run all pytest tests
uv run pytest

# Run specific pytest test
uv run pytest tests/test_with_api_key.py

# Run tests with coverage
uv run pytest --cov=src/mcp_youtube_extract --cov-report=term-missing

Nota: O diretório tests/ contém 4 arquivos:

  • test_context_fix.py - Teste Pytest para funcionalidade de fallback da API de contexto
  • test_with_api_key.py - Teste Pytest para funcionalidade completa com chave de API
  • test_youtube_unit.py - Testes unitários para funcionalidade principal do YouTube
  • test_inspector.py - Script de inspeção autônomo (não é um teste pytest)

Cobertura de Testes: O projeto atualmente tem 62% de cobertura geral com excelente cobertura da funcionalidade principal:

  • youtube.py: 81% de cobertura (lógica de negócios principal)
  • logger.py: 73% de cobertura (utilitários de registro de logs)
  • server.py: 22% de cobertura (manipulação de protocolo MCP)
  • __init__.py: 100% de cobertura (inicialização do pacote)

Executando o Script de Inspeção

O arquivo test_inspector.py é um script autônomo que se conecta ao servidor MCP e valida sua funcionalidade:

# Run the inspection script to test server connectivity and functionality
uv run python tests/test_inspector.py

Este script irá:

  • Conectar-se ao servidor MCP
  • Listar ferramentas, recursos e prompts disponíveis
  • Testar a ferramenta get_yt_video_info com um vídeo de exemplo
  • Validar que o servidor está funcionando corretamente

Usando a Ferramenta do YouTube

O servidor fornece uma ferramenta principal: get_yt_video_info

Esta ferramenta recebe um ID de vídeo do YouTube e retorna:

  • Metadados do vídeo (título, descrição, canal, data de publicação, contagem de visualizações) via yt-info-extract
  • Transcrição do vídeo (com lógica de fallback para diferentes tipos de transcrição) via yt-ts-extract

Exemplo de Uso:

# Extract video ID from YouTube URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
video_id = "dQw4w9WgXcQ"
result = get_yt_video_info(video_id)

Configuração do Cliente

Para usar este servidor MCP com um cliente, adicione a seguinte configuração às configurações do seu cliente:

Usando Instalação via PyPI (Recomendado)

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "mcp_youtube_extract"
    }
  }
}

Com chave de API opcional:

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "mcp_youtube_extract",
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Usando Configuração de Desenvolvimento

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "uv",
      "args": [
        "--directory",
        "<your-project-directory>",
        "run",
        "mcp_youtube_extract"
      ]
    }
  }
}

Com chave de API opcional:

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "uv",
      "args": [
        "--directory",
        "<your-project-directory>",
        "run",
        "mcp_youtube_extract"
      ],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Desenvolvimento

Estrutura do Projeto

mcp_youtube_extract/
├── src/
│   └── mcp_youtube_extract/
│       ├── __init__.py
│       ├── server.py          # MCP server implementation
│       ├── google_api.py      # yt-info-extract integration
│       ├── transcript_api.py  # yt-ts-extract integration
│       ├── youtube.py         # Unified API facade
│       └── logger.py          # Logging configuration
├── tests/
│   ├── __init__.py
│   ├── test_context_fix.py    # Context API fallback tests
│   ├── test_inspector.py      # Server inspection tests
│   ├── test_with_api_key.py   # Full functionality tests
│   └── test_youtube_unit.py   # Unit tests for core functionality
├── logs/                      # Application logs
├── .env                       # Environment variables (create from .env.example)
├── .gitignore                 # Git ignore rules (includes coverage files)
├── pyproject.toml
├── LICENSE                    # MIT License
└── README.md

Estratégia de Testes

O projeto usa uma abordagem abrangente de testes:

  1. Testes Unitários (test_youtube_unit.py): Testam a funcionalidade principal do YouTube com yt-info-extract simulado
  2. Testes de Integração (test_context_fix.py, test_with_api_key.py): Testam a funcionalidade completa do servidor
  3. Validação Manual (test_inspector.py): Ferramenta interativa de inspeção do servidor

Tratamento de Erros

O projeto inclui tratamento robusto de erros:

  • Falhas de extração graciosas: Retorna mensagens de erro apropriadas em vez de travar
  • Múltiplas estratégias de fallback: yt-info-extract fornece fallback automático entre YouTube Data API, yt-dlp e pytubefix
  • Lógica de fallback de transcrição: Múltiplas estratégias para recuperação de transcrições via yt-ts-extract
  • Respostas de erro consistentes: Formato padronizado de mensagens de erro
  • Registro de logs abrangente: Logs detalhados para depuração e monitoramento

Compilação

# Install build dependencies
uv add --dev hatch

# Build the package
uv run hatch build

Licença

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

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Começando

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

Suporte

Se você encontrar problemas ou tiver dúvidas, por favor:

  1. Verifique as issues existentes
  2. Crie uma nova issue com informações detalhadas sobre o seu problema
  3. Inclua logs e mensagens de erro quando aplicável