youtube-kit

youtube-kit

CLI do YouTube (ytk) e servidor MCP, criado para agentes e humanos. Deixe o Claude Code, Codex, Cursor, Claude Desktop ou ChatGPT trabalhar no seu canal: análises, uploads, metadados, playlists e moderação de comentários. Ele lida com vários canais, e você pode executar os mesmos comandos no seu próprio terminal.

Início rápido

uv tool install youtube-kit
ytk auth login      # one-time Google Cloud setup, then pick your channel

Você precisa de uma conta do Google com um canal no YouTube e uv (brew install uv no macOS). A primeira ytk auth login leva cerca de 5 minutos: ela abre cada página do Google Cloud, diz o que clicar e pega o arquivo que você baixa.

ytk analytics --by video --since 90d --limit 5     # your top videos of the last 90 days
ytk comment list --status held                     # comments waiting for review
ytk channel get @mkbhd | jq .stats                 # any public channel

Ou pergunte ao seu agente: "Quais dos meus vídeos tiveram mais visualizações este mês, e há comentários aguardando revisão?"

Use com seu agente

Skill: Claude Code, Codex, Cursor e outros agentes de shell

Uma skill curta ensina o CLI ao agente. Ela carrega apenas quando uma tarefa do YouTube aparece.

claude plugin install youtube-kit --marketplace eukosh/youtube-kit   # Claude Code
codex plugin marketplace add eukosh/youtube-kit                      # Codex, then:
codex plugin add youtube-kit@youtube-kit
npx skills add eukosh/youtube-kit -g                                 # Cursor and others

Os plugins seguem os lançamentos do ytk. O Codex os atualiza na inicialização; o Claude Code faz isso quando você ativa a atualização automática em /plugin → Marketplaces. Com npx skills, execute npx skills update.

MCP: Claude Desktop, ChatGPT e outros clientes MCP

ytk mcp serve as mesmas operações como ferramentas. No Claude Code:

claude mcp add youtube -- uvx youtube-kit mcp

Em clientes configurados com JSON (Claude Desktop, Cursor e outros):

{
  "mcpServers": {
    "youtube": { "command": "uvx", "args": ["youtube-kit", "mcp"] }
  }
}

No aplicativo de desktop do ChatGPT: Configurações → Servidores MCP → Adicionar servidor → STDIO, com o comando uvx youtube-kit mcp. O Codex compartilha essa configuração (codex mcp add youtube -- uvx youtube-kit mcp).

O servidor usa seus logins do ytk auth login. Se você também instalou o ytk com uv tool install, o uvx executa essa versão instalada: uv tool upgrade youtube-kit atualiza ambos. Ainda não configurou? O modelo pode te guiar com a ferramenta setup_guide.

O que cobre

Área	Operações
Análises	totais ou detalhamentos por dia, mês, vídeo, país, dispositivo, sistema operacional, origem de tráfego, local de reprodução, idade, gênero ou status de inscrição
Vídeos	obter, categorias, upload (retomável, com progresso), atualizar metadados, definir miniatura, aguardar processamento, curtir ou não curtir, ver sua avaliação, excluir
Comentários	listar (publicados, em revisão, provável spam), respostas, postar, responder, editar, excluir, aprovar, reter, rejeitar, banir o autor
Playlists	listar, obter, itens, criar, atualizar, definir imagem, adicionar, remover, mover, excluir
Canal	obter, atividade recente, seus canais conectados, informações sobre (descrição, palavras-chave, país, idioma, trailer), banner, marca d'água, seções da página inicial
Pesquisa	vídeos, canais e playlists, filtrados por canal ou data
Inscrições	listar, inscrever-se, cancelar inscrição

Não coberto: legendas, localizações, transmissão ao vivo e assinaturas de canal. ytk --help lista todos os comandos, e a skill os organiza em uma página com receitas de jq.

Canais e login

ytk auth login conecta um canal. Execute novamente para cada um dos seus outros canais, incluindo canais de marca: escolha o que deseja quando o Google perguntar.

ytk channel mine                                           # your channels; one is the default
ytk auth switch @second                                    # change the default
ytk video upload clip.mp4 --title Hi --my-channel @third   # use another channel for one command
ytk auth logout @third

Os comandos funcionam no canal padrão, a menos que --my-channel nomeie outro, por ID UC…, @handle ou título exato. As ferramentas MCP aceitam my_channel da mesma forma, então você pode dizer "faça upload disso para meu canal de jogos". YOUTUBE_CHANNEL define o padrão para um shell ou um servidor MCP.

Por que seu próprio cliente do Google Cloud. A cota diária de 10.000 unidades do YouTube pertence a um projeto Cloud. Um cliente incluído no ytk dividiria uma cota entre todos os seus usuários. A sua é compartilhada apenas pelos seus canais.

Deixe um agente configurar. ytk auth guide (setup_guide via MCP) lista o que falta, com links e os valores a inserir. Com o CLI do gcloud conectado, o agente pode criar o projeto e ativar as APIs para você. O resto precisa do seu navegador. Já tem o JSON do cliente? Execute ytk auth login --client-secrets FILE.

Configuração manual, arquivos e variáveis de ambiente

A configuração guiada faz o seguinte:

1. No Google Cloud Console, crie um projeto e ative a YouTube Data API v3 e a YouTube Analytics API.
2. Em Google Auth Platform, clique em Começar (público Externo). Em Marca, preencha a página inicial (https://github.com/eukosh/youtube-kit), o link da política de privacidade (https://github.com/eukosh/youtube-kit/blob/main/PRIVACY.md) e o domínio autorizado github.com; o Google não publica sem eles. Depois, em Público, clique em Publicar aplicativo. Enquanto o aplicativo estiver em Teste, apenas usuários de teste listados podem entrar e o Google os desconecta após 7 dias.
3. Em Clientes, crie um cliente do tipo Aplicativo de desktop e baixe o JSON dele.
4. ytk auth login --client-secrets path/to/client_secret.json. O Google avisa que não verificou o aplicativo: é seu, então clique em Avançado e depois em Ir para ytk (não seguro).

Dados públicos (pesquisa, vídeos, canais, playlists, comentários) também funcionam apenas com uma chave de API: crie uma no mesmo projeto e export YOUTUBE_API_KEY=..., ou coloque-a no env do servidor MCP. Sem chave, o ytk lê dados públicos pelo seu login.

ytk lembra o handle de cada canal desde o seu login. Após renomear um canal no YouTube, nomeie-o pelo ID UC… ou execute ytk auth login novamente para ele.

As credenciais e o config.toml ficam no diretório de configuração do usuário (~/Library/Application Support/youtube-kit/ no macOS, ~/.config/youtube-kit/ no Linux). ytk auth status imprime os caminhos exatos. Estas variáveis de ambiente os substituem:

Variável	Finalidade
YOUTUBE_API_KEY	Chave de API para dados públicos
YOUTUBE_CLIENT_SECRETS	Caminho para o JSON do cliente OAuth
YOUTUBE_TOKEN_DIR	Diretório de logins armazenados, um arquivo por canal
YOUTUBE_CHANNEL	Canal para trabalhar por padrão (ID UC…, @handle ou título exato), substituindo ytk auth switch
YOUTUBE_CONFIG_FILE	Caminho para config.toml (limites de exclusão)

Feito para agentes

• Saída JSON, códigos de saída para falhas. Cada comando imprime um documento JSON na saída padrão. Em caso de falha, a saída padrão fica vazia, a última linha do erro padrão é {"error": {"type": "not_found", "message": "..."}}, e o código de saída nomeia o tipo: 2 entrada inválida, 3 não encontrado, 4 não autorizado, 5 cota excedida, 6 proibido, 7 rede, 8 confirmação necessária, 9 protegido, 10 tempo esgotado, 1 qualquer outra coisa. A skill diz aos agentes o que fazer com cada um. No terminal, você obtém JSON colorido e erros em frases simples.
• Entradas tolerantes. Passe IDs ou URLs do YouTube coladas, @handles para canais, e datas ou intervalos como 90d.
• Custos de cota antecipados. O --help de cada comando e a descrição de cada ferramenta MCP informam o que ele gasta.
• Um núcleo. O CLI e o servidor MCP são camadas finas sobre o mesmo código, e um teste falha se algum deles perder uma operação.
• Exclusões protegidas. Veja abaixo.

Exclusão

O YouTube não tem lixeira, e agentes cometem erros. Portanto, excluir vídeos, playlists e comentários é protegido:

• Duas etapas. A primeira chamada não exclui nada. No terminal, você recebe um prompt de [y/N]. Um agente recebe saída 8 com uma descrição do alvo e deve executar o comando novamente com --confirm <id>, para que a aprovação sempre nomeie exatamente o que está sendo excluído.

• Limite de danos. Um vídeo com mais de 100 visualizações, ou que seja público e enviado há mais de 7 dias, não pode ser excluído aqui (saída 9). Exclua esses no YouTube Studio. Os limites ficam em config.toml (ytk auth status mostra onde):

  [delete_protection]
  max_views = 100
  max_public_age_days = 7
  

• Aprovação do harness. Peça ao seu agente para perguntar antes de cada exclusão. No Claude Code, adicione isso ao .claude/settings.json:

  {"permissions": {"ask": ["Bash(ytk video delete:*)", "Bash(ytk playlist delete:*)", "Bash(ytk comment delete:*)"]}}
  

• Idempotente. Excluir algo que já não existe é bem-sucedido com "already_gone": true.

Isso impede erros, não um agente determinado. Qualquer coisa que tenha seu token OAuth pode chamar a API diretamente.

Cota

O Google dá a cada projeto Cloud 10.000 unidades por dia, redefinindo à meia-noite, horário do Pacífico. Leituras custam 1 unidade por solicitação, search 100 por página de 50 resultados, a maioria das gravações 50, exclusões protegidas 52 (elas verificam o alvo e a propriedade primeiro), e um upload 1.600. ytk analytics usa a cota separada da YouTube Analytics API.

Contribuindo

Veja CONTRIBUTING.md para a configuração de desenvolvimento e CHANGELOG.md para o que mudou. Relate problemas de segurança em particular, como descrito em SECURITY.md.

Licença

MIT. youtube-kit não é afiliado ou endossado pelo Google ou YouTube. YouTube é uma marca registrada da Google LLC.