maagpi-youtube-mcp

https://github.com/vamsi-kodimela/maagpi-youtube-mcp

Documentação

maagpi-youtube-mcp

npm

maagpi-youtube-mcp é um servidor MCP completo para gerenciamento de canais do YouTube: envie vídeos, agende publicações, consulte análises, modere comentários, gerencie playlists, atualize a identidade visual do canal e opere vários canais do YouTube simultaneamente — tudo a partir de qualquer cliente de IA compatível com MCP.

Encapsula a API oficial YouTube Data API v3 + YouTube Analytics API em uma única superfície MCP com OAuth integrado, rastreamento de cota, cache de respostas e tratamento estruturado de erros.

Transporte

Padrão: stdio (processo local, iniciado pelo seu cliente MCP)
Opcional: Streamable HTTP (YOUTUBE_MCP_TRANSPORT=http) para acesso remoto / multi-cliente
Distribuição: npx maagpi-youtube-mcp — sem necessidade de instalação global
Documentação completa: consulte Referência de Ferramentas abaixo

Autenticação

Este servidor usa Google OAuth 2.0 (credenciais de aplicativo para desktop). Você fornece um Client ID + Client Secret como variáveis de ambiente; o servidor gerencia o fluxo de consentimento no navegador e armazena os tokens de atualização no diretório de configuração do seu sistema operacional sob perfis nomeados (um por canal).

Configuração única no Google Cloud

Google Cloud Console → APIs & Services → Library → ative:
- YouTube Data API v3
- YouTube Analytics API
APIs & Services → OAuth consent screen → External → preencha o nome do aplicativo + seu e-mail → adicione sua conta do Google como Test user.
APIs & Services → Credentials → Create Credentials → OAuth client ID → Tipo de aplicativo Desktop app → copie o Client ID e o Client Secret.

Mantenha seu Client Secret fora do controle de versão. O servidor nunca o transmite para nenhum lugar, exceto accounts.google.com.

Primeira chamada: o servidor abre uma janela do navegador para o consentimento OAuth. Aprove uma vez e os tokens serão salvos automaticamente sob o perfil "default" e renovados automaticamente a partir de então. Adicione mais canais com youtube_account_add.

Conexão Rápida

Escolha seu cliente e cole o trecho no arquivo de configuração correspondente. Substitua your_client_id / your_client_secret pelas suas credenciais OAuth do Google.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Code

~/.claude/settings.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Ou via CLI do Claude Code:

claude mcp add youtube -- npx -y maagpi-youtube-mcp \
  -e YOUTUBE_CLIENT_ID=your_client_id \
  -e YOUTUBE_CLIENT_SECRET=your_client_secret

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

VS Code (extensões compatíveis com MCP)

.vscode/mcp.json (workspace) ou Configurações do Usuário:

{
  "servers": {
    "youtube": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Zed

~/.config/zed/settings.json

{
  "context_servers": {
    "youtube": {
      "command": {
        "path": "npx",
        "args": ["-y", "maagpi-youtube-mcp"],
        "env": {
          "YOUTUBE_CLIENT_ID": "your_client_id",
          "YOUTUBE_CLIENT_SECRET": "your_client_secret"
        }
      }
    }
  }
}

mcporter

mcporter add youtube --command "npx -y maagpi-youtube-mcp" \
  --env YOUTUBE_CLIENT_ID=your_client_id \
  --env YOUTUBE_CLIENT_SECRET=your_client_secret

mcporter call youtube youtube_account_list '{}'

Streamable HTTP (remoto / multi-cliente)

Execute o servidor como um serviço HTTP:

YOUTUBE_MCP_TRANSPORT=http \
YOUTUBE_MCP_HTTP_PORT=3000 \
YOUTUBE_CLIENT_ID=your_client_id \
YOUTUBE_CLIENT_SECRET=your_client_secret \
npx -y maagpi-youtube-mcp
# MCP endpoint: POST http://127.0.0.1:3000/mcp
# Health check: GET  http://127.0.0.1:3000/health

Em seguida, aponte qualquer cliente MCP compatível com HTTP para http://127.0.0.1:3000/mcp.

Referência de Ferramentas

Todas as ferramentas aceitam um parâmetro opcional channel (nome do perfil). Omita-o para usar o perfil ativo.

Gerenciamento de Conta

Ferramenta	Parâmetros	Descrição
`youtube_account_add`	`name`	Conecte um novo canal via OAuth, salve como perfil nomeado
`youtube_account_list`	nenhum	Liste todos os perfis conectados com IDs e status ativo
`youtube_account_switch`	`name`	Defina o perfil ativo padrão
`youtube_account_current`	nenhum	Mostre o perfil atualmente ativo
`youtube_account_remove`	`name`, `confirm: true`	Desconecte e remova um perfil

Vídeos

Ferramenta	Parâmetros	Cota
`youtube_video_upload`	`filePath`, `title`, `privacyStatus`, `channel?`	1600
`youtube_video_get`	`videoId`, `parts?`, `channel?`	1
`youtube_video_list`	`channelId?`, `query?`, `order?`, `maxResults?`, `channel?`	1
`youtube_video_update`	`videoId`, `title?`, `description?`, `tags?`, `channel?`	50
`youtube_video_delete`	`videoId`, `confirm: true`, `channel?`	50
`youtube_video_rate`	`videoId`, `rating` (`like`/`dislike`/`none`), `channel?`	50
`youtube_video_set_thumbnail`	`videoId`, `thumbnailPath`, `channel?`	50

Agendamento e Publicação

Ferramenta	Parâmetros	Cota
`youtube_video_set_privacy`	`videoId`, `privacyStatus`, `channel?`	50
`youtube_video_schedule_publish`	`videoId`, `publishAt` (ISO 8601 futuro), `channel?`	50
`youtube_video_set_premiere`	`videoId`, `premiereAt` (ISO 8601 futuro), `channel?`	50

Análises

Ferramenta	Parâmetros	Cota
`youtube_analytics_video_metrics`	`videoId`, `startDate`, `endDate`, `metrics[]`, `channel?`	1
`youtube_analytics_channel_metrics`	`startDate`, `endDate`, `metrics[]`, `channel?`	1
`youtube_analytics_top_videos`	`startDate`, `endDate`, `metric`, `maxResults?`, `channel?`	1
`youtube_analytics_audience_retention`	`videoId`, `startDate`, `endDate`, `channel?`	1
`youtube_analytics_revenue_report`	`startDate`, `endDate`, `dimensions?`, `channel?`	1

As datas usam YYYY-MM-DD. Métricas comuns de vídeo: views, watchTime, averageViewDuration, averageViewPercentage, likes, shares, subscribersGained, subscribersLost. As métricas de canal adicionam estimatedRevenue, estimatedAdRevenue, grossRevenue, monetizedPlaybacks, cpm, adImpressions.

Comentários

Ferramenta	Parâmetros	Cota
`youtube_comment_list`	`videoId`, `maxResults?`, `order?`, `searchTerms?`, `channel?`	1
`youtube_comment_thread_get`	`commentThreadId`, `maxReplies?`, `channel?`	1
`youtube_comment_reply`	`parentCommentId`, `text`, `channel?`	50
`youtube_comment_delete`	`commentId`, `channel?`	50
`youtube_comment_moderate`	`commentId`, `moderationStatus` (`published`/`heldForReview`/`rejected`), `banAuthor?`, `channel?`	50

Playlists

Ferramenta	Parâmetros	Cota
`youtube_playlist_create`	`title`, `privacyStatus`, `channel?`	50
`youtube_playlist_update`	`playlistId`, `title?`, `description?`, `channel?`	50
`youtube_playlist_delete`	`playlistId`, `confirm: true`, `channel?`	50
`youtube_playlist_get`	`playlistId`, `channel?`	1
`youtube_playlist_list`	`channelId?`, `maxResults?`, `channel?`	1
`youtube_playlist_item_add`	`playlistId`, `videoId`, `position?`, `channel?`	50
`youtube_playlist_item_remove`	`playlistItemId`, `channel?`	50
`youtube_playlist_item_reorder`	`playlistItemId`, `playlistId`, `newPosition`, `channel?`	50
`youtube_playlist_items_list`	`playlistId`, `maxResults?`, `channel?`	1

Gerenciamento de Canal

Ferramenta	Parâmetros	Cota
`youtube_channel_get`	`parts?`, `channel?`	1
`youtube_channel_update`	`title?`, `description?`, `keywords?`, `country?`, `channel?`	50
`youtube_channel_branding_update`	`showRelatedChannels?`, `featuredChannelsTitle?`, `channel?`	50
`youtube_channel_watermark_set`	`channelId`, `imagePath`, `position`, `timing`, `channel?`	50
`youtube_channel_watermark_unset`	`channelId`, `channel?`	50
`youtube_channel_section_list`	`channelId?`, `channel?`	1
`youtube_channel_section_create`	`type`, `title?`, `playlistIds?`, `channel?`	50
`youtube_channel_section_delete`	`sectionId`, `channel?`	50

Exemplos de Prompts

Após conectar, envie estes exemplos ao seu cliente de IA como linguagem natural:

Upload /videos/tutorial.mp4 with title "Getting Started with TypeScript",
description "A beginner's guide", tags ["typescript","programming"], unlisted.

Schedule video dQw4w9WgXcQ to go public on January 20 2026 at 3pm UTC.

Get top 5 videos by views in Q1 2025 for my "main" channel,
and also for my "gaming" channel.

Show me revenue breakdown for 2025-01-01 to 2025-01-31, split by day.

Reply to comment Ugxxxxx with "Thanks for the feedback! Fixed in v2."

Ferramentas que excluem dados exigem confirm: true — seu cliente de IA perguntará antes de prosseguir.

Múltiplos Canais

Conecte qualquer número de contas do YouTube e direcione qualquer uma delas a partir de qualquer ferramenta usando o parâmetro opcional channel — sem necessidade de alternância.

Add a new YouTube channel profile named "gaming"
List all my connected YouTube channel profiles
Switch my active YouTube profile to "gaming"
Upload /videos/clip.mp4 to my "gaming" channel, title "EP1", public

Autenticação via CLI para um perfil nomeado (útil para configurações headless):

npm run auth -- --channel gaming

Cota

A YouTube Data API v3 concede 10.000 unidades/dia por padrão. Cada resposta de ferramenta inclui um campo quota:

{
  "quota": {
    "used": 151,
    "budget": 9000,
    "remaining": 8849,
    "resetAt": "2026-01-15T08:00:00.000Z",
    "warningLevel": "ok",
    "costOfThisCall": 1
  }
}

warningLevel: "ok" → "warn" a 80% → "critical" a 95%.

Proteções integradas

Respostas GET são armazenadas em cache (vídeos 60s, canais 5min, análises 5min) — leituras repetidas custam 0 de cota
Gravações tentam novamente automaticamente em 429/5xx com backoff exponencial (até 3×)
Defina YOUTUBE_MCP_QUOTA_LIMIT abaixo de 10.000 para deixar margem

Formato de Erro

Todos os erros são retornados como conteúdo estruturado de ferramenta — os agentes podem ler e agir sobre eles sem travar:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "YouTube API daily quota has been exceeded.",
    "suggestedFix": "Wait for quota reset at midnight Pacific Time, or increase your quota in Google Cloud Console.",
    "retryable": false,
    "docsUrl": "https://developers.google.com/youtube/v3/getting-started#quota"
  },
  "quota": { "used": 9001, "warningLevel": "critical" }
}

Código	Significado
`AUTH_REQUIRED`	Nenhum token armazenado — fluxo OAuth necessário
`AUTH_TOKEN_EXPIRED`	Token expirado e a renovação falhou — reautentique
`AUTH_INSUFFICIENT_SCOPE`	Escopo OAuth ausente — exclua os tokens e reautentique
`QUOTA_EXCEEDED`	Cota diária esgotada — aguarde o reset à meia-noite (horário do Pacífico)
`PERMISSION_DENIED`	Recurso não pertence à conta autenticada
`VIDEO_NOT_FOUND`	O ID do vídeo não existe ou não está acessível
`PLAYLIST_NOT_FOUND`	ID da playlist não encontrado
`RATE_LIMITED`	Limite temporário de taxa — o servidor tenta novamente automaticamente
`INVALID_PARAMS`	Falha na validação Zod — verifique os tipos dos parâmetros
`PUBLISH_DATE_IN_PAST`	`publishAt` / `premiereAt` deve ser uma data/hora futura

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`YOUTUBE_CLIENT_ID`	✓	—	ID do cliente Google OAuth2
`YOUTUBE_CLIENT_SECRET`	✓	—	Segredo do cliente Google OAuth2
`YOUTUBE_MCP_TRANSPORT`		`stdio`	`stdio` ou `http`
`YOUTUBE_MCP_HTTP_PORT`		`3000`	Porta do servidor HTTP
`YOUTUBE_MCP_HTTP_HOST`		`127.0.0.1`	Endereço de bind HTTP
`YOUTUBE_MCP_QUOTA_LIMIT`		`9000`	Limite de aviso de cota diária
`YOUTUBE_MCP_CACHE_TTL`		por recurso	Substitui todos os TTLs de cache (ms)
`YOUTUBE_MCP_LOG_LEVEL`		`info`	`error` \| `warn` \| `info` \| `debug`

Desenvolvimento

npm install
npm run dev          # run with tsx (requires .env)
npm run auth         # authenticate the default channel profile
npm run auth -- --channel gaming   # authenticate a named profile
npm run typecheck    # tsc --noEmit
npm test             # vitest unit tests
npm run build        # production bundle → dist/index.js
npm pack --dry-run   # verify publish artifact

Por que maagpi-youtube-mcp 🎯

Opere o YouTube a partir de qualquer cliente de IA — Claude, Cursor, Windsurf, Zed, VS Code, mcporter
Gerencie vários canais ao mesmo tempo — sem alternância de contexto, direcione qualquer canal por chamada
Infraestrutura de nível de produção — OAuth, tokens de atualização, rastreamento de cota, novas tentativas, erros estruturados
Cobertura completa da superfície — vídeos, agendamento, análises, comentários, playlists, identidade visual

maagpi-youtube-mcp

Documentação