YouTube Transcript DL MCP Server

🎬 YouTube转录DL MCP服务器

一个全面的MCP（模型上下文协议）服务器，用于提取YouTube视频转录，支持多种传输方式（stdio、SSE、HTTP）、Docker部署和npm包分发。

✨ 特性

• 🎯 多种运输支持：stdio、服务器发送事件（SSE）和HTTP
• 📹 综合转录提取：单个视频、批量处理和播放列表
• 🌍 多语言支持：提取不同语言的成绩单
• 📝 多种输出格式：文本、JSON和SRT字幕格式
• 🚀 高性能：内置缓存和速率限制
• 🐳 Docker就绪：完全支持集装箱化
• 📦 npm包：易于安装和分发
• 🧪 测试驱动开发：全面的测试套件，覆盖率超过90%
• 🔧 TypeScript：完全类型安全和现代JavaScript功能

📦 安装

🔧 作为npm包

npm install -g yt-transcript-dl-mcp

🛠️ 来源

git clone 
cd yt-transcript-dl-repo
npm install
npm run build

🐳 码头工人

# From GitHub Container Registry (recommended)
docker pull ghcr.io/jedarden/yt-transcript-dl-mcp:latest
docker run -p 3001:3001 -p 3002:3002 ghcr.io/jedarden/yt-transcript-dl-mcp:latest --multi-transport

# Build from source
docker build -t yt-transcript-dl-mcp .
docker run -p 3001:3001 -p 3002:3002 yt-transcript-dl-mcp --multi-transport

🚀 用法

🖥️ MCP服务器

以不同模式启动MCP服务器：

# Stdio mode (default)
yt-transcript-dl-mcp start

# SSE mode
yt-transcript-dl-mcp start --transport sse --port 3000

# HTTP mode
yt-transcript-dl-mcp start --transport http --port 3000

# With verbose logging
yt-transcript-dl-mcp start --verbose

💻 CLI工具

使用示例视频测试服务器：

# Test with a YouTube video
yt-transcript-dl-mcp test dQw4w9WgXcQ

# Test with different language
yt-transcript-dl-mcp test dQw4w9WgXcQ --language es

# Test with different format
yt-transcript-dl-mcp test dQw4w9WgXcQ --format srt

🔧 程序化使用

import { YouTubeTranscriptService } from 'yt-transcript-dl-mcp';

const service = new YouTubeTranscriptService();

// Extract single video transcript
const result = await service.getTranscript('dQw4w9WgXcQ', 'en', 'json');
console.log(result);

// Bulk processing
const bulkResult = await service.getBulkTranscripts({
  videoIds: ['dQw4w9WgXcQ', 'jNQXAC9IVRw'],
  outputFormat: 'json',
  language: 'en'
});
console.log(bulkResult);

🛠️ MCP工具

服务器提供以下MCP工具：

get_transcript

从单个YouTube视频中提取文字记录。

参数：

• videoId （必填）：YouTube视频ID或URL
• language （可选）：语言代码（默认值：'en'）
• format （可选）：输出格式-“text”、“json”或“srt”（默认值：“json”）

get_bulk_transcripts

从多个YouTube视频中提取文字记录。

参数：

• videoIds （必填）：YouTube视频ID或URL数组
• language （可选）：语言代码（默认值：'en'）
• outputFormat （可选）：输出格式-“text”、“json”或“srt”（默认值：“json”）
• includeMetadata （可选）：在响应中包含元数据（默认值：true）

get_playlist_transcripts

从YouTube播放列表中的所有视频中提取转录。

参数：

• playlistId （必填）：YouTube播放列表ID或URL
• language （可选）：语言代码（默认值：'en'）
• outputFormat （可选）：输出格式-“text”、“json”或“srt”（默认值：“json”）
• includeMetadata （可选）：在响应中包含元数据（默认值：true）

format_transcript

将现有成绩单数据格式化为不同格式。

参数：

• transcript （必填）：转录数据数组
• format （必填）：输出格式-“文本”、“json”或“srt”

get_cache_stats

获取缓存统计数据和性能指标。

clear_cache

清除转录缓存。

⚙️ 配置

🌍 环境变量

# Server configuration
PORT=3000
HOST=0.0.0.0
MCP_TRANSPORT=stdio

# CORS settings
CORS_ENABLED=true
CORS_ORIGINS=*

# Rate limiting
RATE_LIMIT_WINDOW=900000  # 15 minutes in ms
RATE_LIMIT_MAX=100

# Caching
CACHE_ENABLED=true
CACHE_TTL=3600  # 1 hour in seconds
CACHE_MAX_SIZE=1000

# Logging
LOG_LEVEL=info
LOG_FORMAT=simple

📝 配置文件

创建一个 config.json 文件：

{
  "port": 3000,
  "host": "0.0.0.0",
  "cors": {
    "enabled": true,
    "origins": ["*"]
  },
  "rateLimit": {
    "windowMs": 900000,
    "max": 100
  },
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": 1000
  },
  "logging": {
    "level": "info",
    "format": "simple"
  }
}

🐳 Docker部署

🐙 Docker Compose

version: '3.8'

services:
  yt-transcript-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "dist/health-check.js"]
      interval: 30s
      timeout: 10s
      retries: 3

健康检查

Docker容器包括内置的健康检查：

# Check container health
docker ps
docker exec  node dist/health-check.js

发展

设置

git clone 
cd yt-transcript-dl-repo
npm install

运行测试

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

# Watch mode
npm run test:watch

建筑

# Build TypeScript
npm run build

# Development mode with watch
npm run dev

# Linting
npm run lint
npm run lint:fix

测试MCP服务器

# Test stdio transport
./scripts/test-stdio.sh

# Test with sample video
npm run test:sample

API文档

响应格式

所有成绩单回复均遵循以下结构：

interface TranscriptResponse {
  videoId: string;
  title?: string;
  language: string;
  transcript: TranscriptItem[];
  metadata?: {
    extractedAt: string;
    source: string;
    duration?: number;
    error?: string;
  };
}

interface TranscriptItem {
  text: string;
  start: number;
  duration: number;
}

错误处理

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

• 未找到视频：返回元数据中有错误的空转录
• 私人视频：通过描述性消息进行优雅的错误处理
• 速率限制：内置延迟和重试逻辑
• 网络错误：具有指数回退的自动重试

演出

基准测试

• 单视频提取：\<5秒
• 批量加工：每个视频\<2秒
• 并发请求：10个并发请求的成功率超过90%
• 内存使用：正常负载下小于512MB
• 缓存命中率：重复请求为70%+

优化

• LRU缓存：可配置的TTL和大小限制
• 速率限制：防止API滥用
• 并发处理：针对批量操作进行了优化
• 内存管理：高效的垃圾收集

故障排除

常见问题

1. 未找到视频：检查视频是否公开并有字幕
2. 速率限制：减少并发请求或增加延迟
3. 内存问题：减少缓存大小或定期清除缓存
4. 网络错误：检查互联网连接和防火墙设置

调试模式

启用调试日志记录：

export LOG_LEVEL=debug
yt-transcript-dl-mcp start --verbose

日志

检查日志 logs/ 目录：

tail -f logs/combined.log
tail -f logs/error.log

贡献

1. 分叉存储库
2. 创建要素分支
3. 为新功能编写测试
4. 确保所有测试通过
5. 提交拉取请求

代码的风格

• 对所有代码使用TypeScript
• 遵循ESLint配置
• 编写全面的测试
• 为公共API添加JSDoc注释
• 使用常规提交消息

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

• GitHub问题： 报告错误和功能请求
• 文档： API完整文档
• 示例： 使用示例

更新日志

v1.0.0

• 初始版本
• 具有stdio、SSE和HTTP传输的MCP服务器
• 单视频和批量转录提取
• Docker容器化
• 全面的测试套件
• TypeScript支持
• 缓存和速率限制
• 多种输出格式（文本、JSON、SRT）