YouTube MCP
Provides structured access to YouTube, enabling video search, retrieval of video metadata and normalized audio/video streams, and generation of browser-ready playback URLs without requiring an official YouTube API key or browser automation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@YouTube MCP Search for Pixar's latest movie and show me its duration"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
YouTube MCP — Node.js
English
Overview
This is the maintained Node.js implementation of the standalone YouTube MCP server. The previous Python implementation is preserved in the archive/python branch. It provides structured access to YouTube through Piped without directly interacting with youtube.com, without an official YouTube API key, and without controlling a browser.
AI-generated software disclaimer
This project was fully created with the assistance of artificial intelligence (AI), including its source code, documentation, configuration, and project structure. It has been reviewed and tested to the extent described in this repository, but users should independently review the code and verify that it meets their security, reliability, and legal requirements.
Architecture and features
The server dynamically downloads TeamPiped's official public-instance list, parses and deduplicates API URLs, health-checks each listed API instance, prefers healthy CDN instances with low latency and few failures, and automatically fails over when a backend fails. It keeps state and caches in memory. Playback URLs use the official https://piped.video frontend and a correctly encoded instance parameter.
The project uses the official @modelcontextprotocol/sdk JavaScript SDK. Browser automation is outside the MCP boundary: there are no Playwright, Selenium, CDP, browser profiles, or browser-launching dependencies.
Requirements and installation
Node.js 20 or newer is recommended:
npm installRunning and configuration
Run the default local stdio server:
npm startEnvironment variables:
Variable | Default |
|
|
|
|
|
|
| TeamPiped official raw Markdown URL |
| Official public Invidious list; comma-separated overrides |
|
|
|
|
|
|
For Streamable HTTP, use YOUTUBE_MCP_TRANSPORT=streamable-http; the MCP endpoint is /mcp. The default configuration intentionally binds locally.
Invidious fallback is enabled by default using the five HTTPS clearnet instances currently listed in the official Invidious instance documentation: inv.nadeko.net, invidious.nerdvpn.de, yt.chocolatemoo53.com, invidious.tiekoetter.com, and invidious.f5.si. Set YOUTUBE_MCP_INVIDIOUS_INSTANCES to one or more comma-separated Invidious base URLs to override the list, or set it to an empty string to disable the fallback. Piped remains the primary backend; Invidious is tried only when Piped has no usable instance. Invidious public instances are independent services and may have different availability or privacy policies.
MCP tools
youtube_search(query, filter, limit)searches through Piped and returns concise result metadata.youtube_video(video_id)retrieves metadata and normalized video/audio streams from/streams/{video_id}.youtube_play(video_id, autoplay, listen, quality, sponsorblock)returns a browser-ready URL and never launches a browser.
Errors are returned as structured MCP error content with error and retryable fields. Temporary backend failures are retryable; unavailable videos are non-retryable when the backend returns HTTP 404.
Development and testing
npm test
npm run checkThe tests use mocked HTTP responses and cover TeamPiped parsing, deduplication, invalid entries, health checks, CDN-aware selection, failover, search/video/stream normalization, URL encoding, and configuration. Before production use, perform a live integration check in an environment with outbound HTTPS. Public Piped instances can become unavailable or rate-limit requests.
Security and scope
No credentials, cookies, tokens, arbitrary shell execution, filesystem tools, or YouTube account access are included. The application only needs outbound HTTPS to the TeamPiped list, public Piped APIs, and the Piped frontend. This project is licensed under the GNU General Public License version 3.0. See LICENSE.
Related MCP server: YouTube MCP Server
Português (Brasil)
Visão geral
Esta é a implementação mantida em Node.js do servidor MCP independente para YouTube. A implementação anterior em Python está preservada na branch archive/python. Ela oferece acesso estruturado ao YouTube por meio do Piped sem interagir diretamente com youtube.com, sem chave oficial da API do YouTube e sem controlar um navegador.
Aviso sobre software gerado por IA
Este projeto foi criado integralmente com o auxílio de inteligência artificial (IA), incluindo o código-fonte, a documentação, as configurações e a estrutura do projeto. O projeto foi revisado e testado conforme descrito neste repositório, mas os usuários devem analisar o código por conta própria e verificar se ele atende aos seus requisitos de segurança, confiabilidade e aspectos legais.
Arquitetura e recursos
O servidor baixa dinamicamente a lista oficial de instâncias públicas do TeamPiped, analisa e remove URLs duplicadas, verifica a saúde, prefere instâncias CDN saudáveis com baixa latência e poucas falhas e executa failover automático quando um backend falha. O estado e os caches ficam em memória. Os links de reprodução usam o frontend https://piped.video e um parâmetro instance corretamente codificado.
O projeto usa o SDK oficial @modelcontextprotocol/sdk para JavaScript. A automação de navegador fica fora do limite do MCP: não há Playwright, Selenium, CDP, perfis de navegador ou dependências para iniciar navegadores.
Requisitos e instalação
Recomenda-se Node.js 20 ou mais recente:
npm installExecução e configuração
Execute o servidor local stdio padrão:
npm startAs variáveis de ambiente são equivalentes às listadas na seção em inglês: host 127.0.0.1, porta 8083, transporte stdio, lista oficial do TeamPiped, fallback Invidious habilitado por padrão, atualização da lista em 30 minutos, verificação de saúde em 5 minutos e timeout de 30 segundos. O link de reprodução usa o frontend oficial https://piped.video, com a API selecionada no parâmetro instance. Para Streamable HTTP, use YOUTUBE_MCP_TRANSPORT=streamable-http; o endpoint MCP é /mcp.
A compatibilidade com Invidious é habilitada por padrão usando as cinco instâncias HTTPS clearnet listadas atualmente na documentação oficial de instâncias do Invidious: inv.nadeko.net, invidious.nerdvpn.de, yt.chocolatemoo53.com, invidious.tiekoetter.com e invidious.f5.si. Defina YOUTUBE_MCP_INVIDIOUS_INSTANCES com uma ou mais URLs base separadas por vírgula para substituí-las, ou use uma string vazia para desabilitar o fallback. O Piped continua sendo o backend principal; o Invidious só é usado quando nenhuma instância Piped está disponível.
Ferramentas MCP
youtube_search(query, filter, limit)pesquisa por meio do Piped e retorna metadados concisos.youtube_video(video_id)retorna metadados e streams de vídeo/áudio normalizados usando/streams/{video_id}.youtube_play(video_id, autoplay, listen, quality, sponsorblock)retorna um link pronto para o navegador e nunca abre um navegador.
Erros são retornados como conteúdo MCP estruturado com os campos error e retryable. Falhas temporárias do backend permitem nova tentativa; vídeos indisponíveis são não recuperáveis quando o backend retorna HTTP 404.
Desenvolvimento e testes
Use npm test e npm run check. Os testes usam respostas HTTP simuladas e cobrem análise TeamPiped, duplicatas, entradas inválidas, saúde, seleção CDN, failover, normalização de busca/vídeo/streams, codificação de URLs e configuração. Antes de usar em produção, faça um teste de integração ao vivo em um ambiente com HTTPS de saída. Instâncias públicas do Piped podem ficar indisponíveis ou limitar requisições.
Segurança e escopo
Não há credenciais, cookies, tokens, execução arbitrária de shell, ferramentas de arquivos ou acesso a contas do YouTube. O aplicativo precisa somente de HTTPS de saída para a lista TeamPiped, APIs públicas do Piped e frontend do Piped. Este projeto está licenciado sob a GNU General Public License versão 3.0. Consulte LICENSE.
Available Tools
3 toolsyoutube_playC
Generate a browser-ready Piped or Invidious URL without launching a browser.
Inputs: video_id (required), listen, quality, autoplay, +1 more.
youtube_searchA
Search YouTube through Piped, with optional Invidious fallback.
Inputs: query (required), filter (required), limit.
youtube_videoB
Retrieve video metadata and streams through Piped, with optional Invidious fallback.
Inputs: video_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool serves a distinct purpose: youtube_search for searching, youtube_video for retrieving metadata, and youtube_play for generating playback URLs. No overlap or confusion exists between them.
All tools share a consistent 'youtube_' prefix, but the suffixes mix verbs (search, play) and a noun (video), which is a minor deviation from a strict verb_noun pattern. Still predictable and readable.
Three tools is lean but appropriate for a focused YouTube client covering search, metadata, and playback URL generation. It feels slightly thin but not underdeveloped for its stated scope.
The tool surface covers core operations (search, retrieve metadata, generate playable URL) but lacks common YouTube features like channel or playlist access, comments, or uploads. Some notable gaps exist for broader use cases.
Related MCP Connectors
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
YouTube search, whole channels, video stats, comments and full transcripts with timestamps.
Public YouTube search, channel videos, Shorts and optional video metadata. No API key.
Search YouTube, read video metadata, and fetch transcripts with language preferences
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables interaction with YouTube through search and transcript extraction functionality. Allows searching for videos and retrieving full transcripts with timestamps for content analysis.28-
- AlicenseAqualityDmaintenanceEnables YouTube content browsing, video searching, and metadata retrieval via the YouTube Data API v3. It also facilitates fetching video transcripts for summarization and analysis within MCP-compatible AI clients.71MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search videos, read channels, browse playlists, fetch comments, and get transcripts from YouTube using the YouTube Data API v3 and InnerTube API for captions.2GPL 3.0
- AlicenseAqualityBmaintenanceEnables searching YouTube videos via SerpAPI, returning video details such as title, link, channel, views, duration, and publish date.159 PyPIMIT