YouTube MCP 服务器

一个基于 Python 的模型上下文协议（MCP）服务器，可从 YouTube 视频中提取教育内容——包括文字记录和视觉上有意义的帧——并将其提供给 Claude、ChatGPT 以及任何兼容 MCP 的客户端等 AI 助手使用。

功能简介

给 AI 助手一个 YouTube 链接，它就能：

1. 读取文字记录 — 带时间戳的完整字幕，可直接用于摘要、问答或内容分析。

2. 观看视频 — 一个 5 阶段的计算机视觉流水线可提取信息量最大的帧，对其进行质量评分、去重，并以 base64 编码的 JPEG 格式返回，供 AI“查看”。

无需手动下载。无需复制粘贴。只需粘贴链接并提出问题即可。

工具

get_transcript

使用 youtube-transcript-api 获取视频字幕。

参数：

• url （必填） — YouTube 视频链接

• language （可选，默认值："en"） — 首选字幕语言

• prefer_manual （可选，默认值：true） — 优先使用人工编写的字幕而非自动生成的字幕

返回： 一段干净、带时间戳的文字记录块：

[00:00:00] So I want to start by offering you a free ...
[00:00:15] The key insight here is that ...

get_video_frames

运行完整的视频分析流水线，以呈现最有意义的视觉时刻。

参数：

• url （必填） — YouTube 视频链接

• max_frames （可选，默认值：20） — 返回的最大帧数（硬上限：40）

• scene_threshold （可选，默认值：0.25） — FFmpeg 场景检测灵敏度

• output_width （可选，默认值：640） — 返回 JPEG 的宽度（高度按比例缩放）

• min_importance_score （可选，默认值：0.35） — 最低综合质量评分

返回：

• 元数据：video_id、duration_seconds、pipeline_stats、fallback_used

• 帧块：每个帧块包含 timestamp_ms、composite_score 以及一个 base64 编码的 JPEG 图像

• 一个索引，列出每个返回帧的时间戳和评分

帧流水线（5 个阶段）

快速开始

前置条件

• Python 3.11

• ffmpeg — 视频处理

• Tesseract OCR — 帧中的文本检测

macOS：

brew install ffmpeg tesseract

Ubuntu / Linux：

sudo apt-get install ffmpeg tesseract-ocr tesseract-ocr-eng

Windows： 下载 ffmpeg 和 Tesseract，然后将两者添加到 PATH 中。

验证：

ffmpeg -version
tesseract --version

安装

# Clone the repository
git clone https://github.com/Ayush-Mamgain/youtube-mcp-server.git
cd youtube-mcp-server

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate      # Windows

# Install dependencies
pip install -r requirements.txt

配置

在项目根目录创建 .env 文件：

LOG_LEVEL=DEBUG
MCP_HTTP_PORT=8000

可选调优参数（若省略则从 config.py 默认值加载）：

启动服务器

python server.py

服务器启动于 http://localhost:8000。

连接到 Claude.ai（本地）

1. 启动服务器：python server.py

2. 前往 Claude.ai → 设置 → 集成 → 添加 MCP 服务器

3. 输入：http://localhost:8000/mcp

若要让云端托管的 Claude 访问你的服务器，你需要将其公开暴露（请参阅下方“部署”部分）。

API 端点

项目结构

youtube-mcp-server/
├── server.py              # MCP entry point — FastMCP + Starlette HTTP server
├── config.py              # Loads and validates environment variables
├── logger.py              # stderr-only logging
├── url_parser.py          # Validates YouTube URLs and extracts video IDs
├── transcript.py          # Fetches captions via youtube-transcript-api
├── downloader.py          # Phase 1 — video download with yt-dlp
├── frame_extractor.py     # Phase 2 — scene-change frame extraction via ffmpeg
├── scorer.py              # Phase 3 — multi-signal frame scoring (OpenCV + Tesseract)
├── deduplicator.py        # Phase 4 — perceptual-hash deduplication
├── frame_loader.py        # Phase 5 — resize, JPEG encode, base64
├── video_frames.py        # Orchestrates Phases 1–5 with semaphore and cleanup
├── requirements.txt       # Pinned Python dependencies
└── .gitignore             # Excludes .env, venv, caches, test artifacts

开发工作流

本项目分 9 个独立阶段构建，每个阶段都有对应的测试文件和验证步骤：

黄金法则： 每个阶段在继续之前都必须经过验证。运行 python test_stage{N}.py 进行验证。

部署

Docker 支持已计划但尚未配置。容器化完成后，本节将进行更新。

目前，服务器可直接在安装了 Python 3.11、ffmpeg 和 Tesseract 的任何机器上运行。Docker 就绪后推荐的托管选项：

• Railway

• Fly.io

• Render

部署完成后，将你的 Claude.ai 集成链接更新为：

https://YOUR-DEPLOYMENT-URL/mcp

设计说明

• 所有日志仅输出到 stderr。 stdout 专用于 MCP 通信。

• 线程安全： get_video_frames 流水线使用 threading.Semaphore(1) 防止并发下载压垮系统。

• 自动清理： 视频处理过程中创建的临时文件会在每次运行后删除。

• 严格验证： 视频 ID 会按照 ^[A-Za-z0-9_-]{11}$ 进行验证。仅包含播放列表的链接、频道链接以及格式错误的输入都会被拒绝，并返回清晰的错误信息。

• 优雅降级： 如果所有帧的评分均低于最低重要性阈值，流水线将回退到前 5 帧，并标记 fallback_used: true。

许可证

MIT © Ayush Mamgain

致谢

使用 FastMCP、Starlette、yt-dlp、youtube-transcript-api 和 OpenCV 构建。