# YouTube Whisper MCP Server

一个基于 Whisper 语音识别的 YouTube 视频总结 MCP 服务器，解决原版 MCP 无法处理无字幕视频的问题。

## 核心优势

✅ **无需字幕** - 直接从音频转录，不依赖视频字幕
✅ **中文优化** - 针对中文视频优化，支持中英混合
✅ **完全本地** - 所有处理在本地完成，保护隐私
✅ **免费使用** - 基于开源工具，无 API 费用

## 工作原理

```
YouTube 视频 → yt-dlp 下载音频 → Whisper 转文字 → GPT 总结
```

## 前置要求

在安装此 MCP 服务器之前，请确保已安装以下工具：

### macOS
```bash
# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install yt-dlp ffmpeg

# 安装 Whisper
pip install openai-whisper
# 或者使用 Homebrew
brew install whisper
```

### Linux
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install yt-dlp ffmpeg
pip install openai-whisper

# 或者使用 pipx
pipx install openai-whisper
```

### Windows
```powershell
# 使用 Chocolatey
choco install yt-dlp ffmpeg

# 安装 Python（如果未安装）
choco install python

# 安装 Whisper
pip install openai-whisper
```

## 快速开始

### 1. 安装 Node.js（如果未安装）

推荐使用 nvm 安装：
```bash
# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts

# Windows
# 从 https://nodejs.org 下载安装
```

### 2. 安装 MCP 服务器

```bash
# 克隆或下载此项目
cd youtube-whisper-mcp

# 安装依赖
npm install

# 构建
npm run build
```

### 3. 配置到 OpenCode

在 OpenCode 配置文件中添加：

```json
{
  "mcpServers": {
    "youtube-whisper": {
      "command": "node",
      "args": ["/path/to/your/youtube-whisper-mcp/server.js"]
    }
  }
}
```

或者使用 npx（推荐）：

```json
{
  "mcpServers": {
    "youtube-whisper": {
      "command": "npx",
      "args": ["-y", "youtube-whisper-mcp"]
    }
  }
}
```

**注意**：如需使用 npx 方式，请先发布到 npm：
```bash
npm publish
```

### 4. 测试

```bash
npm test
```

或者运行快速测试脚本：
```bash
node quick-test.js
```

## 可用工具

安装后，以下工具将自动在 OpenCode 中可用：

### 1. summarize_youtube_video

总结 YouTube 视频（无需字幕）

**参数：**
- `url` (必填): YouTube 视频链接
- `summary_length` (可选): 总结长度 - `short` | `medium` | `long`

**使用示例：**
```
"summarize https://www.youtube.com/watch?v=VIDEO_ID"
```

**返回：**
```json
{
  "video_info": {
    "title": "视频标题",
    "url": "https://youtube.com/watch?v=...",
    "duration": "23:10",
    "uploader": "频道名称",
    "views": 24943
  },
  "summary": "视频内容总结...",
  "transcript_length": 5000,
  "full_transcript": "完整转录文本..."
}
```

### 2. get_video_transcript

获取视频完整转录文本

**参数：**
- `url` (必填): YouTube 视频链接

**使用示例：**
```
"get transcript of https://www.youtube.com/watch?v=VIDEO_ID"
```

## 性能优化

### 处理时间估算

- **短视频** (< 5 分钟): 1-2 分钟
- **中等视频** (5-20 分钟): 3-8 分钟
- **长视频** (> 20 分钟): 10-30 分钟

### 加速技巧

1. **使用较小的 Whisper 模型**（server.js 中）：
   ```javascript
   // 在 transcribeAudio 函数中修改
   const command = `whisper "${audioPath}" --model tiny --language Chinese --output_format json`;
   ```

2. **模型选择**（从快到慢，从不准到准）：
   - `tiny` - 最快，最不准确
   - `base` - 平衡选择
   - `small` - 推荐日常使用
   - `medium` - 准确，但较慢
   - `large` - 最准确，最慢

### 硬件要求

- **最低**: 4GB RAM, 2 CPU cores
- **推荐**: 8GB+ RAM, 4+ CPU cores
- **GPU**: 如果有 NVIDIA GPU，Whisper 会自动使用 CUDA 加速

## 常见问题

### Q1: 视频下载失败

**问题**: `ERROR: Unable to download video data: HTTP Error 403`

**解决方案**:
```bash
# 更新 yt-dlp
pip install -U yt-dlp

# 或使用 Homebrew
brew upgrade yt-dlp
```

### Q2: Whisper 转录失败

**问题**: `whisper: command not found`

**解决方案**:
```bash
# 确保 Whisper 已安装
which whisper

# 如果使用 pip 安装，可能需要添加到 PATH
export PATH="$PATH:$(python -m site --user-base)/bin"
```

### Q3: 中文转录效果差

**解决方案**:
1. 使用更大的模型：`--model medium` 或 `--model large`
2. 明确指定语言：`--language Chinese`
3. 确保音频质量良好

### Q4: 处理时间太长

**解决方案**:
1. 使用较小的 Whisper 模型
2. 先下载音频（`-x` 参数）可以加快处理
3. 考虑使用 GPU 加速

### Q5: 如何清理临时文件？

MCP 服务器会在 `/tmp/youtube-whisper-mcp/` 目录自动清理。但您可以手动清理：

```bash
rm -rf /tmp/youtube-whisper-mcp/*
```

## 高级配置

### 集成 OpenAI API 进行更好的总结

默认使用简单截取，您可以通过集成 OpenAI/Claude API 来获得更好的总结效果：

```javascript
// 在 server.js 中修改 summarizeText 函数
async function summarizeText(text) {
  const response = await axios.post('https://api.openai.com/v1/chat/completions', {
    model: 'gpt-3.5-turbo',
    messages: [
      {
        role: 'system',
        content: '你是一个专业的视频内容总结助手。请用简洁的中文总结以下内容。'
      },
      {
        role: 'user',
        content: `请总结这段视频转录内容（500字左右）：\n\n${text}`
      }
    ],
    max_tokens: 1000
  }, {
    headers: {
      'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  return response.data.choices[0].message.content;
}
```

## 与 NoteGPT 集成

如果您喜欢 NoteGPT 的总结效果，可以这样组合使用：

1. **使用 MCP 获取转录**:
   ```
   "get transcript of https://youtube.com/watch?v=..."
   ```

2. **复制转录到 NoteGPT**:
   - 访问 https://notegpt.io/youtube-video-summarizer
   - 粘贴转录文本
   - 让 NoteGPT 总结

## 技术架构

### 核心技术栈

- **yt-dlp**: YouTube 视频下载
- **Whisper**: 语音识别转文字
- **FFmpeg**: 音频处理
- **Node.js + MCP SDK**: MCP 服务器
- **OpenAI/Claude API** (可选): 智能总结

### 目录结构

```
youtube-whisper-mcp/
├── server.js          # MCP 服务器主程序
├── package.json       # 项目配置
├── README.md          # 使用说明
├── quick-test.js      # 快速测试脚本
└── .gitignore        # Git 忽略配置
```

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 此项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 许可证

本项目基于 MIT 许可证开源。

## 致谢

- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - 强大的 YouTube 下载工具
- [OpenAI Whisper](https://github.com/openai/whisper) - 开源语音识别模型
- [Model Context Protocol](https://github.com/modelcontextprotocol) - MCP 标准