使用说明

YouTube摘要MCP服务器

一个强大的MCP（模型上下文协议）服务器，用于通过转录提取、智能摘要、关键点提取和元数据检索来总结YouTube视频。内置 FastMCP 用于简单的、基于装饰器的工具注册和自动MCP协议处理。

韩语文档 |英文文档

📋 项目概述

该项目是通过模型上下文协议（MCP）获取YouTube视频转码、自动摘要和提取关键点的服务器。您可以直接从Claude Desktop、Cursor等支持MCP的AI客户端分析YouTube视频。

🎯 主要功能

📝 转码提取：从YouTube视频中提取字幕文本（支持4种URL格式）
📊 智能摘要：生成不同长度的摘要（短、中、长版本）
提取关键点：基于TF-IDF的自动核心句子提取
🎬 查询元数据：提供视频标题、频道、点击率等信息
🌍 多语言支持：支持7种语言（英语、韩语、西班牙语、法语、德语、日语、中文）
FastMCP框架：基于装饰器的简单实施
🔒 错误处理：全面的错误处理和记录
🏗️ SOLID原则：可扩展的体系结构

🏗️ 体系结构

系统配置图

┌─────────────────────────┐      ┌──────────────────────┐      ┌─────────────┐
│   AI Client             │◄────►│   MCP Server         │◄────►│  YouTube    │
│   (Claude, Cursor, etc) │      │   (FastMCP Python)   │      │  API        │
└─────────────────────────┘      └──────────────────────┘      └─────────────┘
                                           │
                                           ▼
                                  ┌──────────────────┐
                                  │ Core Components  │
                                  │ - Transcript API │
                                  │ - Summarizer     │
                                  │ - Metadata       │
                                  └──────────────────┘

核心组件

MCP服务器核心 (server.py)
- 实施MCP协议（使用FastMCP）
- 管理与客户机的通信
- 处理请求/响应
成绩单检索器 (transcript_retriever.py)
- 提取YouTube转码
- 支持多种URL格式
- 自动检测和回退语言
摘要生成器 (summary_generator.py)
- 基于TF-IDF的文本摘要
- 自动提取关键点
- 多语言Stop Word支持
元数据提取器 (metadata_extractor.py)
- 提取视频元数据
- 创建缩略图URL
配置管理器 (config_manager.py)
- 管理基于Pydantic的设置
- 支持环境变量

🛠️ 技术堆栈

类别	技术
语言	Python 3.10+
MCP框架	FastMCP（模型上下文协议）
YouTube处理	youtube转录api
自然语言处理	NLTK（TF-IDF，停用词）
管理设置	Pydantic，Pydantic设置
包管理	紫外线
测试	pytest
类型检查 mypy的。
代码抛售	黑色，褶边

📁 项目结构

youtube-summary-mcp/
├── youtube_summary_mcp/           # 메인 패키지
│   ├── __init__.py                # 패키지 초기화
│   ├── server.py                  # FastMCP 서버 구현 (stdio)
│   ├── main.py                    # 진입점 (stdio)
│   ├── server_sse.py              # FastMCP 서버 구현 (SSE)
│   ├── main_sse.py                # 진입점 (SSE)
│   ├── asgi.py                    # ASGI 앱 (Uvicorn/Gunicorn용)
│   ├── config_manager.py          # 설정 관리 (Pydantic)
│   ├── transcript_retriever.py    # 트랜스크립트 추출
│   ├── summary_generator.py       # 텍스트 요약 엔진
│   └── metadata_extractor.py      # 메타데이터 추출
│
├── tests/                         # 테스트 스위트
│   ├── test_config_manager.py     # 설정 테스트
│   ├── test_transcript_retriever.py
│   ├── test_summary_generator.py
│   └── test_metadata_extractor.py
│
├── pyproject.toml                 # 프로젝트 설정
├── .env.example                   # 환경 변수 템플릿
├── .gitignore                     # Git 무시 파일
└── README.md                      # 이 파일

🚀 安装和设置

1前提条件

# 필수
- Python 3.10 이상
- uv 패키지 관리자

# 선택사항 (향상된 메타데이터를 위해)
- YouTube Data API Key

2安装依赖性

# 프로젝트 디렉토리로 이동
cd youtube-summary-mcp

# 의존성 설치 및 환경 구성
uv sync

安装的主要软件包：

mcp>=0.1.0 -模型上下文协议
youtube-transcript-api>=0.6.1 -YouTube转码
pydantic>=2.0.0 -数据验证
nltk>=3.9.2 -自然语言处理

3设置环境变量（可选）

.env.example复制 .env 创建文件：

cp .env.example .env

.env 文件内容：

# 로깅 설정
LOG_LEVEL=INFO                    # DEBUG, INFO, WARNING, ERROR, CRITICAL

# 요약 설정
SUMMARY_RATIO=0.35               # 원본의 35% 길이로 요약

# 서버 설정
SERVER_NAME=YouTube Summary MCP
SERVER_VERSION=0.1.0

快速设置（Quick Setup）

只需修改配置文件即可使用！

Claude桌面版설정 （claude_desktop_config.json）

窗户：

{
  "mcpServers": {
    "youtube-summary": {
      "command": "python",
      "args": ["-m", "youtube_summary_mcp.main"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\youtube-summary-mcp"
      }
    }
  }
}

macOS/Linux：

{
  "mcpServers": {
    "youtube-summary": {
      "command": "python3",
      "args": ["-m", "youtube_summary_mcp.main"],
      "env": {
        "PYTHONPATH": "/path/to/youtube-summary-mcp"
      }
    }
  }
}

Cursor设置（cursor_mcp_config.json或settings.json）

{
  "mcp": {
    "servers": [
      {
        "id": "youtube-summary",
        "name": "YouTube Summary",
        "type": "command",
        "command": "python",
        "args": ["-m", "youtube_summary_mcp.main"],
        "env": {
          "PYTHONPATH": "/path/to/youtube-summary-mcp"
        }
      }
    ]
  }
}

设置文件位置：

克劳德桌面（Windows）: C:\Users\[사용자명]\AppData\Roaming\Claude\claude_desktop_config.json
克劳德桌面（macOS）: ~/Library/Application Support/Claude/claude_desktop_config.json
克劳德桌面（Linux）: ~/.config/Claude/claude_desktop_config.json
Cursor（所有操作系统）：设置→MCP部分或 ~/.config/Cursor/User/settings.json

💡 提示: /path/to/youtube-summary-mcp 将部分更改为实际项目路径！

🌐 设置SSE传输方式

除了标准的stdio方法外，您还可以通过Server-Sent Events（SSE）方法运行MCP服务器。SSE是基于HTTP的连接方式，对Web环境或特定MCP客户端很有用。

直接运行SSE（推荐）

自动启动内置FastMCP的Uvicorn服务器。

# 기본값 (0.0.0.0:10719)
uv run youtube-summary-mcp-sse

# 또는 모듈로 직접 실행
uv run python -m youtube_summary_mcp.main_sse

自定义主机/端口设置

# 환경 변수를 통한 설정
MCP_SSE_HOST="127.0.0.1" MCP_SSE_PORT="8080" uv run youtube-summary-mcp-sse

# 여러 변수 설정
export MCP_SSE_HOST="0.0.0.0"
export MCP_SSE_PORT="9000"
export MCP_SSE_PATH="/mcp"  # SSE 엔드포인트 경로 (기본값: /sse)
uv run youtube-summary-mcp-sse

支持的环境变量：

MCP_SSE_HOST：要绑定的主机（默认： 0.0.0.0)
MCP_SSE_PORT：要绑定的端口（默认： 10719)
MCP_SSE_PATH：SSE端点路径（默认： /sse)

作为ASGI服务器运行（高级）

您也可以将FastMCP应用程序作为ASGI服务器（Uvicorn、Gunicorn等）运行：

# Uvicorn으로 실행
uvicorn youtube_summary_mcp.asgi:app --host 0.0.0.0 --port 10719

# 환경 변수와 함께
MCP_SSE_HOST="127.0.0.1" MCP_SSE_PORT="8080" uvicorn youtube_summary_mcp.asgi:app

Claude Desktop设置（SSE方式）

设置方法

启动SSE服务器：
```
# 터미널에서
uv run youtube-summary-mcp-sse
```
服务器 http://0.0.0.0:10719/sse在中运行。
修改Claude Desktop设置文件：

窗户：

{
  "mcpServers": {
    "youtube-summary-sse": {
      "url": "http://localhost:10719/sse",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

macOS/Linux：

{
  "mcpServers": {
    "youtube-summary-sse": {
      "url": "http://localhost:10719/sse",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

重新启动Claude Desktop

stdio与SSE比较

项目	stdio	SSE
传输方式标准I/O HTTP SSE
设置方法	基于command	基于URL
绑定端口	不需要	需要
启动方式自动手动（单独终端）
性能快可靠
Web环境	不支持	支持
推荐用户	在大多数情况下，基于Web的客户端

提示：两者都可以同时运行。stdio始终自动启动，SSE只需在需要时手动启动即可！

🔧 MCP客户端设置（非常重要！）

📌 什么是MCP？

**Model Context Protocol（MCP）**是AI模型访问外部工具和资源的标准方式。通过客户端设置，Claude、Cursor等可以访问YouTube Summary MCP服务器。

配置Claude Desktop

视窗

打开Claude Desktop设置文件：

C:\Users\[사용자명]\AppData\Roaming\Claude\claude_desktop_config.json

添加或修改以下内容：

{
  "mcpServers": {
    "youtube-summary": {
      "command": "python",
      "args": ["-m", "youtube_summary_mcp.main"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\youtube-summary-mcp"
      }
    }
  }
}

或使用绝对路径：

{
  "mcpServers": {
    "youtube-summary": {
      "command": "C:\\Python310\\python.exe",
      "args": [
        "C:\\path\\to\\youtube-summary-mcp\\youtube_summary_mcp\\main.py"
      ]
    }
  }
}

macOS

打开Claude Desktop设置文件：

~/Library/Application\ Support/Claude/claude_desktop_config.json

添加或修改以下内容：

{
  "mcpServers": {
    "youtube-summary": {
      "command": "python3",
      "args": ["-m", "youtube_summary_mcp.main"],
      "env": {
        "PYTHONPATH": "/path/to/youtube-summary-mcp"
      }
    }
  }
}

Linux

打开Claude Desktop设置文件：

~/.config/Claude/claude_desktop_config.json

添加或修改以下内容：

{
  "mcpServers": {
    "youtube-summary": {
      "command": "python3",
      "args": ["-m", "youtube_summary_mcp.main"],
      "env": {
        "PYTHONPATH": "/home/username/path/to/youtube-summary-mcp"
      }
    }
  }
}

重新启动Claude Desktop

🎨 Cursor IDE设置

Windows/MacOS/Linux统一

打开Cursor设置文件：
- 视窗: C:\Users\[사용자명]\AppData\Roaming\Cursor\User\settings.json
- macOS: ~/Library/Application Support/Cursor/User/settings.json
- Linux: ~/.config/Cursor/User/settings.json

添加以下设置：

{
  "mcp": {
    "servers": [
      {
        "id": "youtube-summary",
        "name": "YouTube Summary",
        "type": "command",
        "command": "python",
        "args": ["-m", "youtube_summary_mcp.main"],
        "env": {
          "PYTHONPATH": "/path/to/youtube-summary-mcp"
        }
      }
    ]
  }
}

📌 VS代码（带MCP扩展）

VS Code MCP扩展安装：
- 搜索并安装“Model Context Protocol”
打开VS Code设置 (Ctrl+, 或者 Cmd+,)

修改settings.json：

{
  "mcp.servers": {
    "youtube-summary": {
      "command": "python",
      "args": ["-m", "youtube_summary_mcp.main"],
      "env": {
        "PYTHONPATH": "/path/to/youtube-summary-mcp"
      }
    }
  }
}

🔍 验证设置并解决问题

1.验证服务器是否正常启动

# 터미널에서 직접 실행하여 로그 확인
uv run youtube-summary-mcp

如果正常，将显示以下日志：

2025-10-28 14:59:48,114 - youtube_summary_mcp.server - INFO - Initialized YouTube Summary MCP v0.1.0

2.验证配置文件路径

# Windows (PowerShell)
$env:APPDATA\Claude\claude_desktop_config.json

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
# 또는
cat ~/.config/Claude/claude_desktop_config.json

3.检查python路径

# Python이 올바른 버전인지 확인
python --version          # Python 3.10 이상 필요

# uv를 통한 실행
which uv                  # uv 설치 위치 확인
uv python list           # 설치된 Python 버전 확인

4.在Claude Desktop中查看工具显示

启动Claude Desktop，然后在聊天窗口中“🔧 单击“工具”按钮
检查是否显示“YouTube Summary”服务器
确保列出每个工具（get_transcript、summarize_video等）

📊 可用工具（Tools）

1. get_transcript 📝

提取YouTube视频的转码。

参数：

video_url （必需）：YouTube URL或视频ID
language （可选）：语言代码（默认为“en”）

支持URL格式：

https://www.youtube.com/watch?v=HQU2vbsbXkU
https://youtu.be/HQU2vbsbXkU
https://www.youtube.com/embed/HQU2vbsbXkU
HQU2vbsbXkU  (ID만)

支持的语言：

en -英语
ko -韩语
es -西班牙语
fr -法语
de -德语
ja -日语
zh -中文

示例响应：

{
  "success": true,
  "transcript": "Never gonna give you up, never gonna let you down..."
}

2. 摘要_视频 📊

生成YouTube视频的自动摘要。

参数：

video_url （必需）：YouTube URL或视频ID
summary_length （可选）：摘要长度（默认值：“medium”）
- short -原件的约20%
- medium -原件的约35%
- long -原件的约50%
language （可选）：语言代码（默认为“en”）

示例响应：

{
  "success": true,
  "summary": "이 영상은 유명한 팝 뮤직 비디오입니다...",
  "length": "medium"
}

3. 提取关键点 ✨

自动从视频脚本中提取关键点。

参数：

video_url （必需）：YouTube URL或视频ID
num_points （可选）：要提取的关键点数（默认值：5）
language （可选）：语言代码（默认为“en”）

示例响应：

{
  "success": true,
  "key_points": [
    "Never gonna give you up",
    "Never gonna let you down",
    "Never gonna desert you"
  ],
  "count": 3
}

4. 获取_视频_元数据 🎬

查看YouTube视频的元数据。

参数：

video_url （必需）：YouTube URL或视频ID

示例响应：

{
  "success": true,
  "metadata": "Video ID: HQU2vbsbXkU\nTitle: Rick Astley - Never Gonna Give You Up (Official Video)\nChannel: Unknown\nViews: None"
}

💻 使用示例

在Claude Desktop中使用

打开Claude Desktop
开始新的聊天
在对话窗口中请求：

"이 비디오의 요약을 만들어줄 수 있을까?
https://www.youtube.com/watch?v=HQU2vbsbXkU"

Claude自动使用YouTube Summary MCP工具分析视频。

在Cursor中使用

打开Cursor编辑器
创建chat.md或新文件
开始MCP聊天
请求：

"YouTube 비디오를 요약해줄 수 있을까?
https://youtu.be/HQU2vbsbXkU

핵심 포인트 5개도 함께 추출해줘."

🔒 安全和隐私

本地处理：所有数据仅在本地处理
不需要API Key：YouTube转码API是免费的
无数据缓存：默认情况下不进行转储缓存
记录：敏感信息不会写入日志

🧪 测试

# 모든 테스트 실행
uv run pytest tests/

# 특정 테스트 파일 실행
uv run pytest tests/test_summary_generator.py -v

# 커버리지와 함께 실행
uv run pytest tests/ --cov=youtube_summary_mcp

🔧 开发

代码样式

# 코드 포매팅
uv run black youtube_summary_mcp/ tests/

# Linting
uv run ruff check youtube_summary_mcp/ tests/

# 타입 체킹
uv run mypy youtube_summary_mcp/

📈 性能信息

任务	所需时间
服务器启动-1.8秒
转码提取	5-10秒（根据视频长度）
生成摘要~1秒
提取关键点~0.5秒
查询元数据~2秒

🐛 故障排除

如果服务器无法启动

# 1. 직접 실행하여 에러 메시지 확인
uv run youtube-summary-mcp

# 2. Python 버전 확인 (3.10 이상 필요)
python --version

# 3. 의존성 재설치
uv sync --refresh

“Tool not found”错误

完全退出Claude Desktop/Cursor后重新启动
检查配置文件的JSON格式（逗号、引号等）

无法导入脚本

确保视频中有字幕
受欢迎的视频大部分都有字幕
使用正确的URL格式

📚 文档

有关更多信息，请参阅以下文件：

FASTCMP_REFACTORING.md -迁移到FastMCP的详细报告
QUICKSTART.md -5分钟快速入门指南
用户_内容.md -客户端使用
Developpent.md -开发者指南

📋 支持的语言和格式

语言

英语，韩语，西班牙语，法语，德语，日语，中文

YouTube URL格式

标准： https://www.youtube.com/watch?v=VIDEO_ID
缩短： https://youtu.be/VIDEO_ID
嵌入： https://www.youtube.com/embed/VIDEO_ID
仅ID： VIDEO_ID

摘要长度

短（20%）、中（35%）、长版本（50%）

🎓 版本信息

当前版本：0.2.0（快速MCP）
早期版本：0.1.0（低电平MCP）
状态: 🟢 生产就绪

📝 许可证

MIT许可证-可自由使用、修改和分发。

🤝 贡献

欢迎错误报告、功能请求和完整请求！

📞 支援

如果出现问题：

请重新查看文档
请检查错误日志
请验证配置文件格式

快乐总结！ 🚀

使用说明

YouTube摘要MCP服务器

📋 项目概述

🎯 主要功能

🏗️ 体系结构

系统配置图

核心组件

🛠️ 技术堆栈

📁 项目结构

🚀 安装和设置

1前提条件

2安装依赖性

3设置环境变量（可选）

快速设置（Quick Setup）

Claude桌面版설정 （claude_desktop_config.json）

Cursor设置（cursor_mcp_config.json或settings.json）

🌐 设置SSE传输方式

直接运行SSE（推荐）

自定义主机/端口设置

作为ASGI服务器运行（高级）

Claude Desktop设置（SSE方式）

设置方法

stdio与SSE比较

🔧 MCP客户端设置（非常重要！）

📌 什么是MCP？

配置Claude Desktop

视窗

macOS

Linux

🎨 Cursor IDE设置

Windows/MacOS/Linux统一

📌 VS代码（带MCP扩展）

🔍 验证设置并解决问题

1.验证服务器是否正常启动

2.验证配置文件路径

3.检查python路径

4.在Claude Desktop中查看工具显示

📊 可用工具（Tools）

1. get_transcript 📝

2. 摘要_视频 📊

3. 提取关键点 ✨

4. 获取_视频_元数据 🎬

💻 使用示例

在Claude Desktop中使用

在Cursor中使用

🔒 安全和隐私

🧪 测试

🔧 开发

代码样式

📈 性能信息

🐛 故障排除

如果服务器无法启动

“Tool not found”错误

无法导入脚本

📚 文档

📋 支持的语言和格式

语言

YouTube URL格式

摘要长度

🎓 版本信息

📝 许可证

🤝 贡献

📞 支援

相关 MCP

Flomo笔记服务

3D资产生成服务

文档搜索服务

思维工具服务器

Microsoft 365命令行管理服务器

AI文本人性化服务