YouTube Video Analyzer MCP

An MCP server for analyzing public YouTube videos with Google Gemini. The package keeps its local stdio npm entrypoint for registry and desktop-client usage, and also includes a Streamable HTTP surface for hosted deployments. Local stdio usage is the free BYOK path; hosted HTTP is intended for authenticated deployments. In this repo, Render is the primary production path and Vercel stays as an optional thin adapter.

Features

• analyze_youtube_video for direct short-video or manual-clip analysis
• analyze_youtube_video_audio for audio-only, transcript-grounded analysis of a public YouTube video
• analyze_long_youtube_video for local stdio long videos with Files API-first handling and URL-chunk fallback
• continue_long_video_analysis for local stdio follow-up questions on a long-video sessionId
• start_long_youtube_video_analysis and get_long_youtube_video_analysis_job for remote-safe async long analysis over HTTP
• get_youtube_video_metadata for normalized public YouTube video metadata via the YouTube Data API
• Automatic YouTube URL normalization for watch, live, shorts, embed, and youtu.be links
• Structured JSON output in the video's detected dominant language by default
• MCP-native structuredContent responses with JSON text preserved in content for compatibility
• Structured stderr logging with request correlation IDs for long-running tool diagnostics
• Safe MCP error payloads with machine-readable code, stage, and strategy metadata
• Optional custom JSON schema support for final outputs
• Shared transport-neutral analysis service used by both stdio and HTTP adapters
• Hosted remote MCP endpoint at /api/mcp

Prerequisites

• Node.js 20+
• A Gemini API key
• A YouTube Data API key for the metadata tool
• A public YouTube video URL
• yt-dlp installed locally for the long-video tool, either as a binary or via python -m yt_dlp
• ffmpeg if your yt-dlp setup needs it to merge adaptive video/audio downloads

Setup

1. Install dependencies:

   npm install
   

2. Copy the example environment file and add your API key:

   copy .env.example .env
   

3. Optionally point to a custom yt-dlp binary if it is not on your PATH.

4. Build the server:

   npm run build
   

Running locally

For normal local development:

npm run dev

For the built package entrypoint behavior:

npm run build
npm start

For the local hosted HTTP adapter:

npm run dev:hosted

npm run dev:hosted now starts in protected hosted mode by default. To open it locally without OAuth for manual development only, set ALLOW_UNAUTHENTICATED_HOSTED_DEV=true in your shell or local .env.

For the built hosted HTTP adapter:

npm run build
npm run start:http

For the remote long-analysis worker:

set REDIS_URL=redis://localhost:6379
npm run build
npm run start:worker

For the BullMQ dashboard:

set REDIS_URL=redis://localhost:6379
set ADMIN_USERNAME=admin
set ADMIN_PASSWORD=change-me
npm run build
npm run start:admin

Remote MCP over HTTP

The repository includes a hosted remote MCP entrypoint for web-standard Streamable HTTP:

• api/mcp.ts: optional Vercel adapter
• src/http/mcp.ts: shared HTTP handler
• npm run start:http / render.yaml: primary hosted runtime path

The HTTP adapter reuses the same MCP tool registration logic from src/server.ts.

Render is the canonical deployment target in this repository because it matches the full runtime shape: hosted HTTP endpoint, background worker, Redis-backed jobs, and the admin dashboard. Keep the Vercel-specific files only if you still want a stateless adapter or preview surface.

Hosted HTTP auth is protected by default. Production-style deployments should set OAUTH_ENABLED=true with the required OAUTH_* values. For local hosted development only, you can set `ALLOW_UNAUTHENTICATED_HOSTED_DEV=t

... View full README on GitHub