🎬 YouTube转录MCP服务器
一个全面的YouTube转录提取工具,提供三个不同的界面:
- 🤖 模型上下文协议(MCP)服务器 -用于AI助手和工具
- ⚡ FastAPI HTTP 服务器 -适用于n8n等自动化工具
- 🌐 Gradio Web界面 -便于基于浏览器的访问
✨ 特性
- 📺 使用视频ID或URL从YouTube视频中提取转录
- 🌍 支持多种字幕语言
- 💾 自动保存带有时间戳的文件
- 🔄 针对不同用例的多种接口选项
- 🛡️ 强大的错误处理和验证
📦 安装
🔧 先决条件
- 🐍 Python 3.8+
- 📦 uv包管理器(推荐)或pip
🚀 使用紫外线(推荐)```bash
Clone the repository
git clone https://github.com/Marvel202/yt-mcp-transcript.git
cd yt-mcp-transcript
Create virtual environment and install dependencies
uv sync
### 🐍 使用pip```bash
# Clone the repository
git clone https://github.com/Marvel202/yt-mcp-transcript.git
cd yt-mcp-transcript
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -e .
🚀 用法
1.🤖 MCP服务器模式(适用于AI助手)
VS代码MCP集成
要与VS Code MCP一起使用,请更新您的 mcp.json 配置文件:```json
{
"servers": {
"youtube": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/your/yt-mcp-transcript",
"python",
"src/mcp_youtube.py"
]
}
}
}
> 💡 **备注**:替换 `/path/to/your/yt-mcp-transcript` 使用您的实际项目目录路径。
#### 手动启动MCP服务器
手动启动MCP服务器:```bash
# With uv
uv run python src/mcp_youtube.py --mode mcp
# With pip
python src/mcp_youtube.py --mode mcp
🛠️ 可用的MCP工具
- 📝
get_transcript-从YouTube视频中提取文字记录 - 💾
save_transcript_to_file-将成绩单保存到带有时间戳的文件中
2.⚡ FastAPI HTTP服务器模式(适用于n8n和自动化)
在端口8080上启动HTTP服务器,超时60秒:```bash
🚀 With uv
uv run python src/mcp_youtube.py --mode fastapi
🐍 With pip
python src/mcp_youtube.py --mode fastapi
#### 🌐 可用HTTP端点
**📥 GET/转录/{video_id}**
- 📝 按视频ID提取成绩单
- 💡 例子: `GET http://localhost:8080/transcript/pebgrFQ-C7M`
**📮 POST/成绩单**
- 📝 从URL或视频ID提取转录
- 📋 请求正文: `{"video_url": "https://youtube.com/watch?v=pebgrFQ-C7M"}` 或 `{"video_id": "pebgrFQ-C7M"}`
**💾 POST/转录/保存**
- 💾 提取成绩单并保存到文件
- 📋 请求正文: `{"video_url": "https://youtube.com/watch?v=pebgrFQ-C7M", "filename": "my_transcript.txt"}`
**🏥 GET/健康**
- ✅ 服务器健康检查
#### 🔧 卷曲示例```bash
# 📥 Get transcript by video ID
curl http://localhost:8080/transcript/pebgrFQ-C7M
# 📮 Get transcript from URL
curl -X POST http://localhost:8080/transcript \
-H "Content-Type: application/json" \
-d '{"video_url": "https://youtube.com/watch?v=pebgrFQ-C7M"}'
# 💾 Save transcript to file
curl -X POST http://localhost:8080/transcript/save \
-H "Content-Type: application/json" \
-d '{"video_url": "https://youtube.com/watch?v=pebgrFQ-C7M", "filename": "study_session.txt"}'
3.🌐 Gradio Web界面(基于浏览器)
启动web界面:```bash
🚀 First, start the FastAPI server in one terminal
uv run python src/mcp_youtube.py --mode fastapi
🌐 Then start the Gradio interface in another terminal
uv run python gradio_interface.py
🌐 打开浏览器 `http://localhost:7860` 使用web界面。
## ⚙️ 配置
### 🔗 n8n的配置
与一起使用时 **n8n** (尤其是在Docker中),配置HTTP请求节点:
#### 💾 要将成绩单保存到本地目录:
- **方法**: `POST`
- **统一资源定位符**: `http://host.docker.internal:8080/transcript/save`
- **身体**:JSON格式 `{"video_url": "YOUR_YOUTUBE_URL", "filename": "optional_filename.txt"}`
- **超时**: `60000ms` (60秒)
#### 📝 仅用于转录提取(不保存):
- **方法**: `POST`
- **统一资源定位符**: `http://host.docker.internal:8080/transcript`
- **身体**:JSON格式 `{"video_url": "YOUR_YOUTUBE_URL"}`
- **超时**: `60000ms` (60秒)
> 💡 **备注**:使用 `host.docker.internal` 当n8n在Docker中运行以访问您的本地服务器时。
### 🎬 支持的YouTube URL格式
- 📺 `https://www.youtube.com/watch?v=VIDEO_ID`
- 🔗 `https://youtu.be/VIDEO_ID`
- 📱 `https://m.youtube.com/watch?v=VIDEO_ID`
- 🎯 只有视频ID: `VIDEO_ID`
## 📁 文件结构```bash
yt-mcp-transcript/
├── src/
│ ├── __init__.py
│ └── mcp_youtube.py # 🚀 Main server application
├── gradio_interface.py # 🌐 Web interface
├── transcript/ # 📁 Saved transcripts directory
├── pyproject.toml # ⚙️ Project configuration
├── README.md # 📖 This file
└── test_transcript_saving.py # 🧪 Test script
📤 API响应格式
所有端点都返回JSON响应:
✅ 成功响应:```json
{
"success": true,
"video_id": "pebgrFQ-C7M",
"transcript": "Hello everyone\nWelcome to this video...",
"language": "en",
"with_timestamps": false
}
**❌ 错误响应:**```json
{
"success": false,
"error": "No transcript found for this video",
"video_id": "invalid_id"
}
🛡️ 错误处理
服务器处理各种错误情况:
- 🚫 视频ID或URL无效
- 📵 没有可用成绩单的视频
- 🌐 网络连接问题
- ⏱️ 服务器超时(FastAPI模式限制为60秒)
🧪 测试
测试转录提取:```bash
🧪 Test with the target video
uv run python test_transcript_saving.py
## 🔧 发展
### 🚀 以开发模式运行```bash
# 🤖 MCP mode with auto-reload
uv run python src/mcp_youtube.py --mode mcp
# ⚡ FastAPI mode with auto-reload
uv run python src/mcp_youtube.py --mode fastapi --reload
📦 依赖项
- 🤖
fastmcp>=1.12.2-MCP服务器框架 - 📺
youtube-transcript-api>=1.2.1-YouTube文字记录提取 - ⚡
fastapi>=0.116.1-HTTP API框架 - 🚀
uvicorn>=0.25.0-ASGI服务器 - 🌐
gradio>=5.38.2-Web界面框架 - 📋
pydantic>=2.0.0-数据验证
📄 许可证
MIT许可证-有关详细信息,请参阅许可证文件。
🤝 贡献
- 🍴 分叉存储库
- 🌿 创建要素分支
- ✨ 进行更改
- 🧪 如果适用,添加测试
- 📤 提交拉取请求
🆘 支持
对于问题或疑问:
- 📋 查看GitHub问题页面
- 🐛 创建包含详细信息的新问题
- 📝 包括错误消息和重现步骤
🎯 测试目标视频: pebgrFQ-C7M (与Calm Jazz进行2小时学习)
