YouTube MCP Server

Um servidor MCP para interagir com conteúdo do YouTube, permitindo que modelos de IA acessem e gerenciem dados do YouTube por meio de sua API.

GitHub
1
Experimente este MCPPatrocinado

Documentação

YouTube MCP Server

Servidor Model Context Protocol (MCP) que permite que modelos de IA interajam com conteúdo do YouTube por meio de uma interface padronizada. Este servidor fornece um conjunto de ferramentas para pesquisa de vídeos, análise de conteúdo, processamento de comentários e muito mais.

🌟 Recursos

  • 🔍 Pesquisa e Descoberta de Vídeos

    • Pesquisar vídeos no YouTube
    • Obter vídeos em alta
    • Encontrar conteúdo relacionado
    • Informações do canal

  • 📊 Análise de Conteúdo

    • Informações detalhadas do vídeo
    • Estatísticas do canal
    • Transcrições de vídeo
    • Resumos abrangentes

  • 💬 Recursos Sociais

    • Recuperação de comentários
    • Análise de comentários
    • Dados de interação do usuário

🚀 Início Rápido

Pré-requisitos

1. Instalando o Python

macOS:

# Using Homebrew (recommended)
brew install python@3.11

# Verify installation
python3 --version  # Should show Python 3.11.x

Linux (Ubuntu/Debian):

# Update package list
sudo apt update

# Install Python
sudo apt install python3.11 python3.11-venv

# Verify installation
python3 --version  # Should show Python 3.11.x

Windows:

  1. Baixe o instalador do Python em python.org
  2. Execute o instalador
  3. Marque "Adicionar Python ao PATH" durante a instalação
  4. Abra o Prompt de Comando e verifique:
python --version  # Should show Python 3.11.x

2. Instalando o uv

macOS/Linux:

# Install uv using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

Windows (PowerShell):

# Install uv using the official installer
(Invoke-WebRequest -Uri "https://astral.sh/uv/install.ps1" -UseBasicParsing).Content | pwsh -Command -

# Verify installation
uv --version

Métodos de Instalação Alternativos:

Usando pip (se preferir):

# Install uv using pip
pip install uv

# Verify installation
uv --version

3. Configurando Credenciais do Google Cloud

  1. Crie um projeto no Google Cloud:

    # Go to Google Cloud Console
https://console.cloud.google.com

# Click on "Select a Project" at the top
# Click "New Project"
# Name it (e.g., "youtube-mcp-server")
# Click "Create"

  2. Ative a API de Dados do YouTube:

    # In the Google Cloud Console:
# 1. Go to "APIs & Services" > "Library"
# 2. Search for "YouTube Data API v3"
# 3. Click "Enable"

  3. Crie credenciais OAuth 2.0:

    # In the Google Cloud Console:
# 1. Go to "APIs & Services" > "Credentials"
# 2. Click "Create Credentials" > "OAuth client ID"
# 3. Select "Desktop app" as application type
# 4. Name it (e.g., "YouTube MCP Client")
# 5. Click "Create"

  4. Baixe e armazene as credenciais:

    # 1. After creating credentials, click "Download JSON"
# 2. Rename the downloaded file to 'credentials.json'
# 3. Move it to your project root:
mv ~/Downloads/client_secret_*.json ./credentials.json

# Verify the file exists and has correct permissions
ls -l credentials.json  # Should show -rw------- (readable only by you)

  5. Autenticação pela primeira vez:

    # Run the server once to authenticate
python mcp_videos.py

# This will:
# 1. Open your browser
# 2. Ask you to sign in to Google
# 3. Grant permissions to the application
# 4. Create a token.pickle file (automatically ignored by git)

⚠️ Notas de Segurança Importantes:

  • Nunca envie credentials.json ou token.pickle para o git
  • Mantenha suas credenciais seguras e não as compartilhe
  • Se as credenciais forem comprometidas:
    1. Acesse o Google Cloud Console
    2. Exclua as credenciais comprometidas
    3. Crie novas credenciais
    4. Atualize seu credentials.json local

Instalação

  1. Clone o repositório:
git clone https://github.com/yourusername/youtube-mcp-server.git
cd youtube-mcp-server
  1. Crie e ative um ambiente virtual:
# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows (Command Prompt):
.venv\Scripts\activate
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
  1. Instale as dependências usando uv:
# Install project in editable mode
uv pip install -e .

# If you encounter any SSL errors on macOS, you might need to:
export SSL_CERT_FILE=/etc/ssl/cert.pem
  1. Configure as credenciais da API do YouTube:
    • Acesse o Google Cloud Console
    • Crie um novo projeto
    • Ative a API de Dados do YouTube v3
    • Crie credenciais (ID do Cliente OAuth 2.0)
    • Baixe as credenciais e salve como client_secrets.json

Configuração de Desenvolvimento

Para desenvolvimento, você pode querer instalar ferramentas adicionais:

# Install development dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Configuração

  1. Crie um arquivo .env na raiz do projeto:
# Required environment variables
YOUTUBE_API_KEY=your_api_key_here

# Optional configuration
YOUTUBE_API_QUOTA_LIMIT=10000  # Daily quota limit
YOUTUBE_API_REGION=US          # Default region
  1. Verifique sua configuração:
# Check if credentials are properly set up
ls -l credentials.json  # Should exist and be readable
ls -l .env             # Should exist and be readable
ls -l token.pickle     # Should exist after first authentication

# Test the server
python mcp_videos.py

🛠️ Uso

Iniciando o Servidor

python mcp_videos.py

Ferramentas Disponíveis

  1. Pesquisar Vídeos
@mcp.tool()
async def get_videos(search: str, max_results: int)
  1. Obter Informações do Vídeo
@mcp.tool()
async def get_video_info(video_id: str)
  1. Obter Detalhes do Canal
@mcp.tool()
async def get_channel_details(channel_id: str)
  1. Obter Comentários do Vídeo
@mcp.tool()
async def get_video_comments_tool(video_id: str, max_results: int = 100)
  1. Obter Vídeos em Alta
@mcp.tool()
async def get_trending_videos_tool(region_code: str = "US", max_results: int = 50)
  1. Obter Vídeos Relacionados
@mcp.tool()
async def get_related_videos_tool(video_id: str, max_results: int = 25)
  1. Resumir Vídeo
@mcp.tool()
async def summarize_video(video_id: str, include_comments: bool = True)
  1. Gerar Flashcards de Vídeo
@mcp.tool()
async def generate_video_flashcards(
    video_id: str,
    max_cards: int = 10,
    categories: Optional[List[str]] = None,
    difficulty: Optional[str] = None
)

Esta ferramenta gera flashcards educacionais a partir do conteúdo do vídeo:

  • Cria diferentes tipos de cartões (Preencher lacunas, Perguntas e Respostas, Definição)
  • Inclui carimbos de tempo para referência no vídeo
  • Categoriza os cartões por tipo e dificuldade
  • Fornece estatísticas dos cartões

Exemplo de uso:

# Generate 15 flash cards from a video
cards = generate_video_flashcards(
    video_id="dQw4w9WgXcQ",
    max_cards=15,
    categories=["Q&A", "Definition"],
    difficulty="Medium"
)

# Generate all types of cards
cards = generate_video_flashcards(
    video_id="dQw4w9WgXcQ",
    max_cards=20
)

Tipos de Cartões:

  • Preencher lacunas: Testa a recordação de termos ou conceitos específicos
  • Perguntas e Respostas: Perguntas sobre pontos-chave do vídeo
  • Definição: Explica conceitos importantes

Níveis de Dificuldade:

  • Fácil: Recordação e compreensão básicas
  • Médio: Aplicação de conceitos
  • Difícil: Conceitos complexos e relações
  1. Gerar Quiz de Vídeo
@mcp.tool()
async def generate_video_quiz(video_id: str) -> str

Esta ferramenta gera um quiz abrangente a partir do conteúdo do vídeo:

  • Cria perguntas de múltipla escolha
  • Gera afirmações verdadeiro/falso
  • Inclui perguntas de preencher lacunas
  • Usa metadados do vídeo, transcrição e descrição
  • Fornece respostas e explicações

Exemplo de uso:

# Generate a quiz from a video
quiz = generate_video_quiz("dQw4w9WgXcQ")

Recursos do Quiz:

  • Perguntas de Múltipla Escolha

    • Baseadas no conteúdo do vídeo
    • Incluem metadados do vídeo
    • Testam a compreensão de conceitos-chave

  • Perguntas Verdadeiro/Falso

    • Testam conhecimento factual
    • Baseadas nas estatísticas do vídeo
    • Verificam a compreensão de afirmações

  • Preencher Lacunas

    • Testa a recordação de termos específicos
    • Usa o conteúdo da transcrição
    • Foca em conceitos-chave

Formato do Quiz:

=== Video Quiz ===
Title: [Video Title]
Channel: [Channel Name]
URL: [Video URL]

Question 1 (Multiple Choice):
[Question text]
1. [Option 1]
2. [Option 2]
3. [Option 3]
4. [Option 4]

Answer: [Correct answer]
------------------

Question 2 (True/False):
[Statement]

Answer: True/False
------------------

Question 3 (Fill in the blank):
[Question with blank]

Answer: [Correct answer]
------------------

A ferramenta de quiz:

  • Gera exatamente 10 perguntas
  • Mistura diferentes tipos de perguntas
  • Inclui contexto do vídeo
  • Fornece feedback imediato
  • Usa metadados do vídeo para as perguntas
  • Incorpora o conteúdo da transcrição
  • Testa diferentes níveis de compreensão

📊 Arquitetura

O projeto segue uma arquitetura modular:

graph TD
    A[LLM Client] --> B[MCP Client]
    B --> C[MCP Server]
    C --> D[YouTube API]
    C --> E[Tool Registry]
    C --> F[Data Formatter]

    subgraph "Tools"
        E --> E1[Video Tools]
        E --> E2[Channel Tools]
        E --> E3[Comment Tools]
        E --> E4[Analysis Tools]
    end

🔧 Desenvolvimento

Estrutura do Projeto

youtube-mcp-server/
├── mcp_videos.py          # Main server implementation
├── youtube_api.py         # YouTube API client
├── yt_helper.py          # Helper functions
├── requirements.txt       # Project dependencies
├── .env                  # Environment variables
├── .gitignore           # Git ignore rules
└── README.md            # This file

Adicionando Novas Ferramentas

  1. Crie uma nova função assíncrona em mcp_videos.py
  2. Decore-a com @mcp.tool()
  3. Implemente a lógica da ferramenta
  4. Adicione tratamento de erros adequado
  5. Atualize a documentação

📝 Documentação da API

Formatos de Resposta

  1. Formato de Vídeo
{
    "title": str,
    "channel_title": str,
    "duration": str,
    "description": str,
    "view_count": int,
    "like_count": int,
    "comment_count": int,
    "url": str,
    "published_at": str
}
  1. Formato de Canal
{
    "title": str,
    "subscriber_count": int,
    "video_count": int,
    "view_count": int,
    "description": str,
    "published_at": str
}
  1. Formato de Comentário
{
    "author": str,
    "text": str,
    "like_count": int,
    "published_at": str
}

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça commit das suas alterações
  4. Envie para o branch
  5. Crie um Pull Request

📄 Licença

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

🙏 Agradecimentos

📞 Suporte

Para suporte, por favor:

  1. Consulte a documentação
  2. Abra uma issue
  3. Entre em contato com os mantenedores

🔄 Atualizações

Mantenha-se atualizado com o projeto:

🔒 Segurança

Tratamento de Dados Sensíveis

⚠️ IMPORTANTE: Nunca envie arquivos sensíveis para o repositório:

  • token.pickle
  • client_secrets.json
  • arquivos .env
  • Quaisquer outros arquivos de credenciais

Esses arquivos são automaticamente ignorados pelo .gitignore, mas se você os enviar acidentalmente:

  1. Remova-os do rastreamento do git:
git rm --cached token.pickle
git rm --cached client_secrets.json
  1. Revogue e regenere quaisquer credenciais expostas
  2. Atualize seu arquivo .env local com novas credenciais
  3. Nunca compartilhe ou exponha esses arquivos publicamente

Boas Práticas

  1. Sempre use variáveis de ambiente para dados sensíveis
  2. Mantenha as credenciais no arquivo .env (já em .gitignore)
  3. Rotacione regularmente chaves de API e tokens
  4. Use OAuth 2.0 para autenticação
  5. Monitore os alertas de verificação de segredos do GitHub

🖥️ Configuração do Claude Desktop

1. Instalar o Claude Desktop

  1. Baixe o Claude Desktop:

    • Visite Claude Desktop
    • Baixe a versão apropriada para o seu sistema operacional:
      • macOS: arquivo .dmg
      • Windows: instalador .exe
      • Linux: pacote .AppImage ou .deb

  2. Instale o Aplicativo:

    # macOS
# 1. Open the .dmg file
# 2. Drag Claude to Applications folder
# 3. Open from Applications

# Windows
# 1. Run the .exe installer
# 2. Follow the installation wizard
# 3. Launch from Start Menu

# Linux (Ubuntu/Debian)
sudo dpkg -i claude-desktop_*.deb  # For .deb package
# OR
chmod +x Claude-*.AppImage         # For AppImage
./Claude-*.AppImage

2. Configurar o Cliente MCP

  1. Abra as Configurações do Claude Desktop:

    • Clique no ícone de engrenagem (⚙️) ou
    • Use o atalho de teclado:
      • macOS: Cmd + ,
      • Windows/Linux: Ctrl + ,

  2. Adicione a Configuração MCP:

    • Navegue até "Configurações MCP" ou "Configurações Avançadas"
    • Adicione a seguinte configuração:
    {
  "mcpServers": {
    "youtube_videos": {
      "command": "uv",
      "args": [
        "--directory",
        "<your base directory>/youtube-mcp-server",
        "run",
        "mcp_videos.py"
      ]
    }
  }
}

  3. Substitua o Caminho:

    • Substitua <your base directory> pelo caminho real do seu projeto

    • Exemplo para diferentes sistemas operacionais:

      // macOS/Linux
"/Users/username/Documents/youtube-mcp-server"

// Windows
"C:\\Users\\username\\Documents\\youtube-mcp-server"

  4. Verifique a Configuração:

    # Test the MCP server path
cd "<your base directory>/youtube-mcp-server"
uv run mcp_videos.py

3. Usando o Claude com MCP

  1. Inicie o Claude Desktop

  2. Conecte-se ao Servidor MCP:

    • O servidor deve iniciar automaticamente
    • Você verá um indicador de status da conexão
    • As ferramentas disponíveis serão listadas na interface

  3. Teste a Conexão:

    # Try a simple command
get_videos("python programming", max_results=5)

Solução de Problemas de Conexão MCP

  1. O Servidor Não Inicia:

    # Check if the path is correct
pwd  # Should show your project directory

# Verify Python environment
which python  # Should point to your virtual environment

# Check uv installation
uv --version

  2. Problemas de Conexão:

    • Verifique se o servidor está em execução
    • Verifique o caminho da configuração
    • Certifique-se de que todas as dependências estejam instaladas
    • Verifique os logs no Claude Desktop

  3. Erros Comuns:

    # Path not found
# Solution: Use absolute path in configuration

# Permission denied
# Solution: Check file permissions
chmod +x mcp_videos.py

# Module not found
# Solution: Verify virtual environment
source .venv/bin/activate  # or appropriate activation command