youtube-video-analyzer

YouTube 视频分析器 MCP

使用 Google Gemini 分析公开 YouTube 视频的 MCP stdio 服务。

可通过任何兼容 MCP 的客户端使用它来总结视频、提取带时间戳的见解、分析口述内容、检查元数据、处理较长的 VOD，并针对可复用的长视频会话提出后续问题。

功能

• 使用 Gemini 分析公开 YouTube 视频。
• 通过音频优先指令分析以语音为主的视频。
• 通过 YouTube Data API 获取标准化的 YouTube 元数据。
• 使用 yt-dlp 和 ffmpeg 从 YouTube 视频中提取高分辨率 JPEG 帧。
• 通过必需的 MCP 任务分析长视频和 VOD。
• 为不支持 MCP 任务的客户端，通过兼容的后台作业分析长视频和 VOD。
• 复用长视频会话以提出后续问题。
• 本地下载工具不可用时，回退到按 URL 分块处理。
• 提供自定义响应模式时，返回结构化 JSON。

要求

• Node.js 20 或更高版本。
• Gemini API 密钥。
• 可选：用于查询元数据的 YouTube Data API 密钥。
• 可选，建议用于获得最佳长视频支持：yt-dlp 和 ffmpeg。

快速开始

使用 npx 直接从 MCP 客户端运行已发布的包：

{
  "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。只有使用 get_youtube_video_metadata 时才需要设置 YOUTUBE_API_KEY。

全局设置

你也可以全局安装此包并保存可复用的配置：

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

之后，MCP 客户端可以使用：

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

包

此仓库是一个小型 npm 工作区：

• @ludylops/video-analysis-core：位于 packages/video-analysis-core 中，可复用且与传输方式无关的视频分析逻辑。
• @ludylops/youtube-video-analyzer-mcp：位于仓库根目录中的 MCP stdio 服务适配器。

MCP 服务依赖核心包，因此 SaaS 应用、CLI、技能和其他集成可以复用相同的分析逻辑，而不依赖 MCP。

本地开发

npm install
npm run build
npm test
npm start

本地运行时，将 .env.example 复制为 .env：

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

工具

• get_youtube_analyzer_capabilities：检查本地对长视频策略的支持情况。
• get_youtube_video_metadata：获取标准化的公开 YouTube 元数据。
• get_youtube_video_frame：提取指定时间戳处的高分辨率 JPEG 帧；可选先使用 Gemini 修正时间戳，再进行本地提取。
• analyze_youtube_video：分析短视频或有时长限制的片段窗口。
• analyze_youtube_video_audio：使用音频优先指令分析以语音为主的视频。
• analyze_long_youtube_video：通过必需的 MCP 任务分析长视频或 VOD。
• start_long_youtube_analysis：启动长视频后台作业并返回 jobId。
• get_long_youtube_analysis_status：查询长视频后台作业的状态。
• get_long_youtube_analysis_result：获取已完成的长视频后台作业结果。
• cancel_long_youtube_analysis：取消长视频后台作业。
• continue_long_video_analysis：通过必需的 MCP 任务，对此前的长视频会话提出后续问题。

详细的输入、策略和示例，请参阅 docs/tools.md。

长视频

对于 VOD 和长视频，请先调用 get_youtube_analyzer_capabilities。

原生长视频工具需要执行 MCP 任务。如果你的客户端仅支持带固定超时时间（例如 120 秒）的同步工具调用，请使用兼容性作业工作流：start_long_youtube_analysis、轮询 get_long_youtube_analysis_status，然后获取 get_long_youtube_analysis_result。你也可以使用 analyze_youtube_video 分析较短的限定时间段。

如果 yt-dlp、ffmpeg 和可写的临时目录可用，请使用 strategy=auto 或 strategy=uploaded_file 调用 analyze_long_youtube_video。此方式可以创建可重复使用的 Gemini 文件会话，并返回 sessionId。

如果本地下载工具不可用，请使用 strategy=url_chunks。此方式无需在本地下载媒体，但可能需要调用 Gemini 更多次。

请阅读完整指南。

文档

• 安装
• 配置
• 工具
• 长视频
• 示例
• 故障排除
• 发布流程
• 更新日志

隐私与限制

此服务会将 YouTube URL、提示词以及相关媒体或衍生片段发送给 Google Gemini。使用 strategy=uploaded_file 时，本地工具可能会先下载临时媒体，再上传到 Gemini。get_youtube_video_frame 会下载一个较小的临时高质量视频片段，并返回精确的 JPEG 帧；如果请求了时间戳细化，Gemini 仅用于选择时间戳，不会用于生成图像像素。使用 strategy=url_chunks 时，此服务不会在本地下载媒体，但可能会调用 Gemini 更多次。

私人、已删除、年龄受限、仅会员可观看、受 DRM 保护或受地区限制的视频可能无法访问，具体取决于 YouTube 和 Gemini 的访问权限。用户有责任遵守 YouTube 条款、Gemini API 条款、版权规定和当地法律。

项目布局

• packages/video-analysis-core/src：可复用的视频分析核心。
• src/server.ts：MCP 服务和工具注册。
• src/mcp-server-main.ts：stdio 传输入口。
• src/platform-runtime：MCP 服务使用的运行时适配器。
• bin/youtube-video-analyzer-mcp.js：CLI 封装程序和设置流程。
• src/test：测试套件。

贡献

欢迎贡献。请先阅读 CONTRIBUTING.md，在提交更改前运行 npm test，并针对影响用户可见行为的更改更新 CHANGELOG.md。

许可证

MIT。请参阅 LICENSE。