youtube-mcp-server

Un servidor MCP remoto que expone la YouTube Data API v3 como herramientas, mediante Streamable HTTP, de modo que se pueda añadir a claude.ai como conector personalizado.

Sin dependencias. Sin paso de compilación. node src/server.js es todo el proyecto.

Herramientas

Las transcripciones se omiten deliberadamente. captions.download requiere OAuth y permiso de edición sobre el vídeo, así que una clave de API solo puede obtener los subtítulos de los vídeos que poseas. Las bibliotecas de scraping no oficiales están, según numerosos informes, bloqueadas desde los rangos de IP de la nube, que es exactamente donde se ejecuta este servidor.

Related MCP server: mcp-server-youtube

Cuota

Un proyecto dispone de 10.000 unidades al día en el bucket general, y search.list está en un bucket aparte con un límite de 100 llamadas al día. Eso condicionó el diseño de las herramientas: youtube_channel_videos usa channels.list → playlistItems.list → videos.list en lugar de search.list?channelId=, de modo que explorar un canal cuesta 3 unidades generales en lugar de una de las únicas cien búsquedas diarias.

Ejecutar en local

cp .env.example .env        # add your YOUTUBE_API_KEY
export $(grep -v '^#' .env | xargs)
npm start

curl localhost:3000/health

curl -s localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

Pruebas

npm test

Ejecuta el handshake completo de MCP, ambos modos de transporte, las cinco herramientas y las rutas de error contra una API de YouTube simulada. No requiere clave de API ni conexión de red.

Desplegar en Railway

1. Sube este repositorio a GitHub.

2. Railway → New Project → Deploy from GitHub repo → elige el repositorio.

3. Variables → añade YOUTUBE_API_KEY.

4. Settings → Networking → Generate Domain.

5. Comprueba que https://<your-domain>/health devuelve "apiKeyConfigured": true.

Railway establece PORT por su cuenta; el servidor se vincula a 0.0.0.0 y lee esa variable.

Añadir a claude.ai

Customize → Connectors → Add custom connector → https://<your-domain>/mcp

No se necesitan campos OAuth — el servidor no tiene autenticación por defecto. Para restringir el acceso, define MCP_AUTH_TOKEN y añade Bearer <token> en la cabecera authorization de las Request del conector.

Variables de entorno

Notas de diseño

Sin estado. Cada POST es autocontenido — sin Mcp-Session-Id, sin mapa de sesiones —, así que un reinicio o una segunda réplica nunca produce "No valid session ID provided".

La negociación de contenido coincide con el SDK de referencia: un frame SSE cuando el cliente envía Accept: text/event-stream, y un cuerpo JSON plano en caso contrario.

GET y DELETE en /mcp devuelven 405, que es lo que la especificación de Streamable HTTP espera de un servidor sin flujo iniciado por el servidor y sin sesión que cerrar.

Sin validación de la cabecera Origin y sin protección contra DNS rebinding. Esas defensas están pensadas para servidores MCP vinculados a localhost; si se dejan activas en un despliegue público, rechazan las solicitudes de la propia Anthropic, que es una causa habitual de los timeouts de initialize.

Los fallos de las herramientas se devuelven como contenido isError: true en lugar de errores JSON-RPC, de modo que Claude puede leer qué ha fallado y ajustar su enfoque, en vez de que la llamada muera en la capa de transporte.

Los resultados se truncan a 120k caracteres, por debajo del tope de ~150k que claude.ai aplica a los resultados de herramientas.