MCP YouTube 字幕服务器

这是一个 Model Context Protocol 服务器，能够从 YouTube 视频中检索字幕。该服务器通过一个简单的接口直接访问视频字幕，非常适合内容分析和处理。

目录

• 功能
• 开始使用
  • 前提条件
  • 安装
• 使用方法
  • 基本配置
  • 测试
  • 故障排除与维护
• API 参考
• 开发
• 贡献
• 许可

功能

✨ 主要功能：

• 从 YouTube 视频中提取字幕
• 支持多种语言
• 以连续或段落模式格式化文本
• 检索视频标题和元数据
• 自动段落分割
• 文本规范化和 HTML 实体解码
• 强大的错误处理
• 时间戳和重叠检测

开始使用

前提条件

• Node.js 18 或更高版本

安装

我们提供了两种安装方法：

方法 1：手动配置（推荐用于生产环境）

1. 创建或编辑 Claude Desktop 配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 添加以下配置：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "-y",
        "@sinco-lab/mcp-youtube-transcript"
      ]
    }
  }
}

适用于 macOS 的快速设置脚本：

# Create directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude

# Create or update config file
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << 'EOL'
{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "-y",
        "@sinco-lab/mcp-youtube-transcript"
      ]
    }
  }
}
EOL

方法 2：通过 Smithery（仅限开发）

npx -y @smithery/cli install @sinco-lab/mcp-youtube-transcript --client claude

⚠️ 注意：此方法不推荐用于生产环境，因为它依赖于 Smithery 的代理服务。

使用方法

基本配置

要与 Claude Desktop / Cursor / cline 一起使用，请确保您的配置匹配：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": ["-y", "@sinco-lab/mcp-youtube-transcript"]
    }
  }
}

测试

与 Claude 应用程序

1. 安装后重启 Claude 应用程序
2. 使用简单命令进行测试：

   https://www.youtube.com/watch?v=AJpK3YTTKZ4 总结这个视频
   

示例输出：

与 MCP Inspector

# Clone and setup
git clone https://github.com/sinco-lab/mcp-youtube-transcript.git
cd mcp-youtube-transcript
npm install
npm run build

# Launch inspector
npx @modelcontextprotocol/inspector node "dist/index.js"

# Access http://localhost:5173 and try these commands:
# 1. List Tools: clink `List Tools`
# 2. Test get_transcripts with:
#    url: "https://www.youtube.com/watch?v=AJpK3YTTKZ4"
#    lang: "en" (optional)
#    enableParagraphs: false (optional)

故障排除与维护

检查 Claude 日志

要监控 Claude 的日志，可以使用以下命令：

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

这将显示日志文件的最后 20 行，并继续显示新增加的条目。

注意：Claude 应用会自动为 MCP 服务器日志文件添加 mcp-server- 前缀。例如，我们的服务器的日志将写入到 mcp-server-youtube-transcript.log 文件中。

清理 npx 缓存

如果您遇到与 npx 缓存相关的问题，可以手动清理缓存：

rm -rf ~/.npm/_npx

这将移除缓存的包并允许你重新开始。

API 参考

get_transcripts

从 YouTube 视频中获取字幕。

参数:

• url (字符串, 必填): YouTube 视频 URL 或 ID
• lang (字符串, 可选): 语言代码 (默认: "en")
• enableParagraphs (布尔值, 可选): 启用段落模式 (默认: false)

响应格式:

{
  "content": [{
    "type": "text",
    "text": "Video title and transcript content",
    "metadata": {
      "videoId": "video_id",
      "title": "video_title",
      "language": "transcript_language",
      "timestamp": "processing_time",
      "charCount": "character_count",
      "transcriptCount": "number_of_transcripts",
      "totalDuration": "total_duration",
      "paragraphsEnabled": "paragraph_mode_status"
    }
  }]
}

开发

项目结构

├── src/
│ ├── index.ts            # Server entry point
│ ├── youtube.ts          # YouTube transcript fetching logic
├── dist/                 # Compiled output
└── package.json

关键组件

• YouTubeTranscriptFetcher: 核心字幕获取功能
• YouTubeUtils: 文本处理和工具函数

功能与能力

• 错误处理:

  • 无效的 URL/ID
  • 不可用的字幕
  • 语言可用性
  • 网络错误
  • 请求频率限制

• 文本处理:

  • HTML 实体解码
  • 标点符号规范化
  • 空格规范化
  • 智能段落检测

贡献

我们欢迎贡献！请随时提交问题和拉取请求。

许可证

此项目根据 MIT 许可证发布 - 查看 LICENSE 文件以获取详细信息。

相关项目

• mcp-servers
• MCP Inspector