{
  "markdown": "# YouTube Video Analyzer MCP\n\nMCP stdio server for analyzing public YouTube videos with Google Gemini.\n\nUse 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.\n\n## What It Can Do\n\n- Analyze public YouTube videos with Gemini.\n- Analyze speech-focused videos with audio-first instructions.\n- Fetch normalized YouTube metadata through the YouTube Data API.\n- Extract high-resolution JPEG frames from YouTube videos with `yt-dlp` and `ffmpeg`.\n- Analyze long videos and VODs through required MCP tasks.\n- Analyze long videos and VODs through compatibility background jobs for clients without MCP task support.\n- Reuse long-video sessions for follow-up questions.\n- Fall back to URL chunking when local download tools are unavailable.\n- Return structured JSON when you provide a custom response schema.\n\n## Requirements\n\n- Node.js 20 or newer.\n- A Gemini API key.\n- Optional: a YouTube Data API key for metadata lookup.\n- Optional for best long-video support: `yt-dlp` and `ffmpeg`.\n\n## Quick Start\n\nUse the published package directly from your MCP client with `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"youtube-analyzer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ludylops/youtube-video-analyzer-mcp\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your_gemini_key_here\",\n        \"YOUTUBE_API_KEY\": \"optional_youtube_key_here\"\n      }\n    }\n  }\n}\n```\n\n`GEMINI_API_KEY` is required. `YOUTUBE_API_KEY` is only required for `get_youtube_video_metadata`.\n\n## Global Setup\n\nYou can also install the package globally and store reusable config:\n\n```bash\nnpm install -g @ludylops/youtube-video-analyzer-mcp\nyoutube-video-analyzer-mcp setup\n```\n\nThen your MCP client can use:\n\n```json\n{\n  \"mcpServers\": {\n    \"youtube-analyzer\": {\n      \"command\": \"youtube-video-analyzer-mcp\"\n    }\n  }\n}\n```\n\n## Packages\n\nThis repository is a small npm workspace:\n\n- `@ludylops/video-analysis-core`: reusable transport-agnostic video analysis logic in `packages/video-analysis-core`.\n- `@ludylops/youtube-video-analyzer-mcp`: MCP stdio server adapter in the repository root.\n\nThe 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.\n\n## Local Development\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm start\n```\n\nCopy `.env.example` to `.env` for local runs:\n\n```bash\nGEMINI_API_KEY=your_gemini_api_key_here\nYOUTUBE_API_KEY=your_youtube_api_key_here\nGEMINI_MODEL=gemini-2.5-pro\nYT_DLP_PATH=yt-dlp\nMCP_LOG_LEVEL=warn\n```\n\n## Tools\n\n- `get_youtube_analyzer_capabilities`: inspects local support for long-video strategies.\n- `get_youtube_video_metadata`: fetches normalized public YouTube metadata.\n- `get_youtube_video_frame`: extracts a high-resolution JPEG frame at a timestamp, with optional Gemini timestamp refinement before local extraction.\n- `analyze_youtube_video`: analyzes short videos or bounded clip windows.\n- `analyze_youtube_video_audio`: analyzes speech-focused videos using audio-first instructions.\n- `analyze_long_youtube_video`: analyzes long videos or VODs as a required MCP task.\n- `start_long_youtube_analysis`: starts a background long-video job and returns a `jobId`.\n- `get_long_youtube_analysis_status`: polls a background long-video job.\n- `get_long_youtube_analysis_result`: fetches a completed background long-video job result.\n- `cancel_long_youtube_analysis`: cancels a background long-video job.\n- `continue_long_video_analysis`: asks follow-up questions for a previous long-video session as a required MCP task.\n\nFor detailed inputs, strategies, and examples, see [docs/tools.md](docs/tools.md).\n\n## Long Videos\n\nFor VODs and long videos, call `get_youtube_analyzer_capabilities` first.\n\nThe 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`.\n\nWhen `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`.\n\nWhen local download tools are unavailable, use `strategy=url_chunks`. It avoids local media downloads, but can require more Gemini calls.\n\nRead the full guide in [docs/long-videos.md](docs/long-videos.md).\n\n## Documentation\n\n- [Installation](docs/installation.md)\n- [Configuration](docs/configuration.md)\n- [Tools](docs/tools.md)\n- [Long videos](docs/long-videos.md)\n- [Examples](docs/examples.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Release process](docs/release-process.md)\n- [Changelog](CHANGELOG.md)\n\n## Privacy And Limitations\n\nThis 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.\n\nPrivate, 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.\n\n## Project Layout\n\n- `packages/video-analysis-core/src`: reusable video analysis core.\n- `src/server.ts`: MCP server and tool registration.\n- `src/mcp-server-main.ts`: stdio transport entry point.\n- `src/platform-runtime`: runtime adapters used by the MCP server.\n- `bin/youtube-video-analyzer-mcp.js`: CLI wrapper and setup flow.\n- `src/test`: test suite.\n\n## Contributing\n\nContributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), run `npm test` before opening changes, and update [CHANGELOG.md](CHANGELOG.md) for user-visible behavior changes.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 6386,
  "sha": "67623b2296b4da01e383304aa63dd3125ee5b7f6b2594f07559694ac0821ed24",
  "repo_slug": "ludmila-omlopes/youtube-video-analyzer-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ludmila_omlopes_youtube_video__40818a89/readme"
}