# Video to Text MCP Server
一个基于 Model Context Protocol (MCP) 的服务器，用于下载视频、提取音频并将语音转换为文本。
## 功能
- 从 YouTube 或其他支持的平台下载视频（使用 yt-dlp）
- 提取音频并转换为适合语音识别的格式（使用 ffmpeg）
- 使用 OpenAI Whisper 将音频转换为文本
- 支持多种输出格式：纯文本 (.txt)、JSON (.json)、SRT (.srt)、VTT (.vtt)
- 从音频 URL 直接下载音频并转换为文本
- 返回转录文本的本地文件路径
## 前提条件
在使用此 MCP 服务器之前，需要安装以下依赖：
### 1. yt-dlp
用于下载视频的工具。
```bash
# macOS (使用 Homebrew)
brew install yt-dlp
# 其他平台
pip install yt-dlp
```
### 2. ffmpeg
用于音频提取和转换的工具。
```bash
# macOS (使用 Homebrew)
brew install ffmpeg
# Ubuntu/Debian
sudo apt-get install ffmpeg
# 其他平台请参考官方文档
```
### 3. OpenAI Whisper
用于语音转文本的 AI 模型。
```bash
pip install openai-whisper
```
Whisper 需要 Python 3.8 或更高版本。安装后，Whisper 会自动下载所需的模型文件（首次运行时会下载 base 模型）。
## 安装 MCP 服务器
1. 克隆或复制此项目到本地
2. 安装 Node.js 依赖：
```bash
cd video-to-text-mcp
npm install
npm run build
```
## 配置 MCP
在 Claude Desktop 或其他 MCP 客户端中配置此服务器：
### Claude Desktop 配置
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"video-to-text": {
"command": "node",
"args": ["/path/to/video-to-text-mcp/build/index.js"],
"env": {
"WHISPER_MODEL": "base" // 可选：指定 Whisper 模型（tiny, base, small, medium, large）
}
}
}
}
```
### 环境变量
- `WHISPER_MODEL`: 指定 Whisper 模型（默认：base）
- `TEMP_DIR`: 指定临时文件目录（默认：系统临时目录）
## 使用方法
MCP 服务器提供两个工具：`video_to_text` 和 `voice_to_text`
### video_to_text 工具
用于下载视频、提取音频并转换为文本。
#### 参数
- `url` (必需): 视频的 URL（支持 YouTube、Bilibili 等 yt-dlp 支持的平台）
- `outputFormat` (可选): 输出格式，可选值：`txt`、`json`、`srt`、`vtt`（默认：`txt`）
- `language` (可选): 语言代码，例如 `en`（英语）、`zh`（中文）、`ja`（日语）等
#### 示例调用
```json
{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"outputFormat": "txt",
"language": "en"
}
```
### voice_to_text 工具
用于从音频 URL 直接下载音频文件并转换为文本。
#### 参数
- `url` (必需): 音频文件的 URL（支持 .mp3、.wav、.m4a 等格式）
- `outputFormat` (可选): 输出格式，可选值：`txt`、`json`、`srt`、`vtt`（默认：`txt`）
- `language` (可选): 语言代码，例如 `en`（英语）、`zh`（中文）、`ja`（日语）等
#### 示例调用
```json
{
"url": "https://example.com/audio.mp3",
"outputFormat": "txt",
"language": "en"
}
```
### 响应
成功时返回：
- 转录文本的预览（前 500 个字符）
- 转录文件的完整本地路径
错误时返回详细的错误信息。
## 开发
### 构建项目
```bash
npm run build
```
### 开发模式（监听文件变化）
```bash
npm run dev
```
### 测试
```bash
npm test
```
### 调试 MCP
```bash
npm run debug
```
## 技术栈
- **MCP SDK**: `@modelcontextprotocol/sdk`
- **类型检查**: TypeScript
- **参数验证**: Zod
- **视频下载**: yt-dlp（通过子进程调用）
- **音频处理**: ffmpeg（通过子进程调用）
- **语音识别**: OpenAI Whisper（通过子进程调用）
## 注意事项
1. **临时文件**: 处理过程中会创建临时文件，处理完成后不会自动清理。临时文件存储在系统的临时目录中。
2. **网络依赖**: 需要网络连接以下载视频和 Whisper 模型（首次运行）。
3. **处理时间**: 视频下载和语音识别可能需要较长时间，取决于视频长度和系统性能。
4. **存储空间**: 需要足够的磁盘空间存储视频、音频和转录文件。
## 故障排除
### 常见问题
1. **"Command not found: yt-dlp"**
- 确保 yt-dlp 已正确安装并在 PATH 中
- 尝试运行 `which yt-dlp` 确认
2. **"Command not found: ffmpeg"**
- 确保 ffmpeg 已正确安装并在 PATH 中
- 尝试运行 `which ffmpeg` 确认
3. **"Command not found: whisper"**
- 确保 OpenAI Whisper 已安装：`pip install openai-whisper`
- 尝试运行 `whisper --help` 确认
4. **Whisper 模型下载失败**
- 检查网络连接
- 手动下载模型：`whisper --model base --language en example.mp3`
5. **内存不足**
- 处理大型视频时可能需要大量内存
- 考虑使用较小的 Whisper 模型（如 tiny 或 base）
### 日志
所有处理日志输出到 stderr，可以在 MCP 客户端中查看。
## 许可证
ISC
