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。

Related MCP server: YT-NINJA

环境要求

• Node.js 20 或更高版本。

• 一个 Gemini API 密钥。

• 可选：用于元数据查询的 YouTube Data API 密钥。

• 可选（以获得最佳长视频支持）：yt-dlp 和 ffmpeg。

快速开始

直接从您的 MCP 客户端使用已发布的包，通过 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 是必需的。YOUTUBE_API_KEY 仅在 get_youtube_video_metadata 时需要。

全局安装

您也可以全局安装该包并存储可复用的配置：

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

然后您的 MCP 客户端可以使用：

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

包结构

这是一个小型 npm workspace：

• @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 以及可写的临时目录可用时，请使用 analyze_long_youtube_video 并设置 strategy=auto 或 strategy=uploaded_file。此路径可以创建可复用的 Gemini 文件会话并返回 sessionId。

当本地下载工具不可用时，请使用 strategy=url_chunks。它避免了本地媒体下载，但可能需要更多的 Gemini 调用。

完整指南请参阅 docs/long-videos.md。

文档

• 安装

• 配置

• 工具

• 长视频

• 示例

• 故障排除

• 发布流程

• 更新日志

隐私与限制

此服务器会将 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。