YouTube Video Analyzer MCP

MCP stdio server for analyzing public YouTube videos with Google Gemini.

Use it from any MCP-compatible client to summarize videos, extract timestamped insights, analyze spoken content, inspect metadata, work with long VODs, and ask follow-up questions against reusable long-video sessions.

What It Can Do

• Analyze public YouTube videos with Gemini.
• Analyze speech-focused videos with audio-first instructions.
• Fetch normalized YouTube metadata through the YouTube Data API.
• Extract high-resolution JPEG frames from YouTube videos with yt-dlp and ffmpeg.
• Analyze long videos and VODs through required MCP tasks.
• Analyze long videos and VODs through compatibility background jobs for clients without MCP task support.
• Reuse long-video sessions for follow-up questions.
• Fall back to URL chunking when local download tools are unavailable.
• Return structured JSON when you provide a custom response schema.

Requirements

• Node.js 20 or newer.
• A Gemini API key.
• Optional: a YouTube Data API key for metadata lookup.
• Optional for best long-video support: yt-dlp and ffmpeg.

Quick Start

Use the published package directly from your MCP client with npx:

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "npx",
      "args": ["-y", "@ludylops/youtube-video-analyzer-mcp"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_key_here",
        "YOUTUBE_API_KEY": "optional_youtube_key_here"
      }
    }
  }
}

GEMINI_API_KEY is required. YOUTUBE_API_KEY is only required for get_youtube_video_metadata.

Global Setup

You can also install the package globally and store reusable config:

npm install -g @ludylops/youtube-video-analyzer-mcp
youtube-video-analyzer-mcp setup

Then your MCP client can use:

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "youtube-video-analyzer-mcp"
    }
  }
}

Packages

This repository is a small npm workspace:

• @ludylops/video-analysis-core: reusable transport-agnostic video analysis logic in packages/video-analysis-core.
• @ludylops/youtube-video-analyzer-mcp: MCP stdio server adapter in the repository root.

The MCP server depends on the core package, so SaaS apps, CLIs, skills, and other integrations can reuse the same analysis logic without depending on MCP.

Local Development

npm install
npm run build
npm test
npm start

Copy .env.example to .env for local runs:

GEMINI_API_KEY=your_gemini_api_key_here
YOUTUBE_API_KEY=your_youtube_api_key_here
GEMINI_MODEL=gemini-2.5-pro
YT_DLP_PATH=yt-dlp
MCP_LOG_LEVEL=warn

Tools

• get_youtube_analyzer_capabilities: inspects local support for long-video strategies.
• get_youtube_video_metadata: fetches normalized public YouTube metadata.
• get_youtube_video_frame: extracts a high-resolution JPEG frame at a timestamp, with optional Gemini timestamp refinement before local extraction.
• analyze_youtube_video: analyzes short videos or bounded clip windows.
• analyze_youtube_video_audio: analyzes speech-focused videos using audio-first instructions.
• analyze_long_youtube_video: analyzes long videos or VODs as a required MCP task.
• start_long_youtube_analysis: starts a background long-video job and returns a jobId.
• get_long_youtube_analysis_status: polls a background long-video job.
• get_long_youtube_analysis_result: fetches a completed background long-video job result.
• cancel_long_youtube_analysis: cancels a background long-video job.
• continue_long_video_analysis: asks follow-up questions for a previous long-video session as a required MCP task.

For detailed inputs, strategies, and examples, see docs/tools.md.

Long Videos

For VODs and long videos, call get_youtube_analyzer_capabilities first.

The native long-video tools require MCP task execution. If your client only supports synchronous tool calls with a fixed timeout such as 120 seco

... View full README on GitHub