# MCP YouTube 字幕服务器
## 基本信息
- Slug: `sinco-lab-mcp-youtube-transcript`
- Source: modelscope
- Publisher: @sinco-lab/mcp-youtube-transcript
- Categories: search / image-and-video-processing
- Hosted: Yes
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@sinco-lab/mcp-youtube-transcript
## 简介
一个模型上下文协议服务器，可实现从YouTube视频中检索字幕。该服务器通过简单界面提供对视频字幕和 subtitle 的直接访问，使其非常适合内容分析和处理。
## 安装提示

```bash
适用于 macOS 的快速设置脚本： ```bash # 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
```

## MCP Server 详情

# MCP YouTube 字幕服务器

[![smithery 徽章](https://smithery.ai/badge/@sinco-lab/mcp-youtube-transcript)](https://smithery.ai/server/@sinco-lab/mcp-youtube-transcript)

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

<a href="https://glama.ai/mcp/servers/@sinco-lab/mcp-youtube-transcript">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@sinco-lab/mcp-youtube-transcript/badge" alt="mcp-youtube-transcript" />
</a>

## 目录
- [功能](#功能)
- [开始使用](#开始使用)
  - [前提条件](#前提条件)
  - [安装](#安装)
- [使用方法](#使用方法)
  - [基本配置](#基本配置)
  - [测试](#测试)
  - [故障排除与维护](#故障排除与维护)
- [API 参考](#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. 添加以下配置：

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


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

```bash
# 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（仅限开发）

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


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

## 使用方法

### 基本配置

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

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


### 测试

#### 与 Claude 应用程序

1. 安装后重启 Claude 应用程序
2. 使用简单命令进行测试：
   ```plaintext
   https://www.youtube.com/watch?v=AJpK3YTTKZ4 总结这个视频
   ```

示例输出：
![演示](./assets/demo.png)

#### 与 MCP Inspector

```bash
# 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 的日志，可以使用以下命令：

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


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

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

#### 清理 `npx` 缓存

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

```bash
rm -rf ~/.npm/_npx
```

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

## API 参考

### get_transcripts

从 YouTube 视频中获取字幕。

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

**响应格式:**
```json
{
  "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](LICENSE) 文件以获取详细信息。

## 相关项目

- [mcp-servers](https://github.com/modelcontextprotocol/servers)
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)