The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Youtube Video Analyzer listing page.
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.
yt-dlp and ffmpeg.yt-dlp and ffmpeg.Use the published package directly from your MCP client with npx:
GEMINI_API_KEY is required. YOUTUBE_API_KEY is only required for get_youtube_video_metadata.
You can also install the package globally and store reusable config:
Then your MCP client can use:
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.
Copy .env.example to .env for local runs:
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.
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 seconds, use the compatibility job workflow: start_long_youtube_analysis, poll get_long_youtube_analysis_status, then fetch get_long_youtube_analysis_result. You can also analyze shorter bounded windows with analyze_youtube_video.
When yt-dlp, ffmpeg, and a writable temp directory are available, use analyze_long_youtube_video with strategy=auto or strategy=uploaded_file. This path can create a reusable Gemini file session and return a sessionId.
When local download tools are unavailable, use strategy=url_chunks. It avoids local media downloads, but can require more Gemini calls.
Read the full guide in docs/long-videos.md.
This server sends the YouTube URL, prompts, and relevant media or derived chunks to Google Gemini. With strategy=uploaded_file, local tools may download temporary media before uploading it to Gemini. get_youtube_video_frame downloads a small temporary high-quality video window and returns an exact JPEG frame; if timestamp refinement is requested, Gemini is used only to choose a timestamp, not to create image pixels. With strategy=url_chunks, the server avoids local media downloads but may make more Gemini calls.
Private, deleted, age-restricted, member-only, DRM-protected, or region-blocked videos may fail depending on YouTube and Gemini access. Users are responsible for complying with YouTube terms, Gemini API terms, copyright rules, and local law.
packages/video-analysis-core/src: reusable video analysis core.src/server.ts: MCP server and tool registration.src/mcp-server-main.ts: stdio transport entry point.src/platform-runtime: runtime adapters used by the MCP server.bin/youtube-video-analyzer-mcp.js: CLI wrapper and setup flow.src/test: test suite.Contributions are welcome. Start with CONTRIBUTING.md, run npm test before opening changes, and update CHANGELOG.md for user-visible behavior changes.
MIT. See LICENSE.