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

用于下载视频的工具。

# macOS (使用 Homebrew)
brew install yt-dlp

# 其他平台
pip install yt-dlp

2. ffmpeg

用于音频提取和转换的工具。

# macOS (使用 Homebrew)
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# 其他平台请参考官方文档

3. OpenAI Whisper

用于语音转文本的 AI 模型。

pip install openai-whisper

Whisper 需要 Python 3.8 或更高版本。安装后，Whisper 会自动下载所需的模型文件（首次运行时会下载 base 模型）。

安装 MCP 服务器

1. 克隆或复制此项目到本地
2. 安装 Node.js 依赖：

cd video-to-text-mcp
npm install
npm run build

配置 MCP

在 Claude Desktop 或其他 MCP 客户端中配置此服务器：

Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.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（日语）等

示例调用

{
  "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（日语）等

示例调用

{
  "url": "https://example.com/audio.mp3",
  "outputFormat": "txt",
  "language": "en"
}

响应

成功时返回：

• 转录文本的预览（前 500 个字符）
• 转录文件的完整本地路径

错误时返回详细的错误信息。

开发

构建项目

npm run build

开发模式（监听文件变化）

npm run dev

测试

npm test

调试 MCP

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