Yt MCP Transcript

🎬 YouTube转录MCP服务器

一个全面的YouTube转录提取工具，提供三个不同的界面：

1. 🤖 模型上下文协议（MCP）服务器 -用于AI助手和工具
2. ⚡ FastAPI HTTP 服务器 -适用于n8n等自动化工具
3. 🌐 Gradio Web界面 -便于基于浏览器的访问

✨ 特性

• 📺 使用视频ID或URL从YouTube视频中提取转录
• 🌍 支持多种字幕语言
• 💾 自动保存带有时间戳的文件
• 🔄 针对不同用例的多种接口选项
• 🛡️ 强大的错误处理和验证

📦 安装

🔧 先决条件

• 🐍 Python 3.8+
• 📦 uv包管理器（推荐）或pip

🚀 使用紫外线（推荐）

# 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

# 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 配置文件：

{
  "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服务器：

# 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秒：

# 🚀 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/健康

• ✅ 服务器健康检查

🔧 卷曲示例

# 📥 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界面：

# 🚀 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

📁 文件结构

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响应：

✅ 成功响应：

{
  "success": true,
  "video_id": "pebgrFQ-C7M",
  "transcript": "Hello everyone\nWelcome to this video...",
  "language": "en",
  "with_timestamps": false
}

❌ 错误响应：

{
  "success": false,
  "error": "No transcript found for this video",
  "video_id": "invalid_id"
}

🛡️ 错误处理

服务器处理各种错误情况：

• 🚫 视频ID或URL无效
• 📵 没有可用成绩单的视频
• 🌐 网络连接问题
• ⏱️ 服务器超时（FastAPI模式限制为60秒）

🧪 测试

测试转录提取：

# 🧪 Test with the target video
uv run python test_transcript_saving.py

🔧 发展

🚀 以开发模式运行

# 🤖 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许可证-有关详细信息，请参阅许可证文件。

🤝 贡献

1. 🍴 分叉存储库
2. 🌿 创建要素分支
3. ✨ 进行更改
4. 🧪 如果适用，添加测试
5. 📤 提交拉取请求

🆘 支持

对于问题或疑问：

1. 📋 查看GitHub问题页面
2. 🐛 创建包含详细信息的新问题
3. 📝 包括错误消息和重现步骤

______________________________________________________________________

🎯 测试目标视频: pebgrFQ-C7M （与Calm Jazz进行2小时学习）