MCP Video Extraction

🚀 MCP视频与音频文本提取服务器

这是一个MCP服务器，可从各种视频平台和音频文件中提取文本。该服务器实现了模型上下文协议（MCP），为音频转录服务提供标准化访问。

🚀 快速开始

本服务支持从多个平台下载视频并提取音频，使用前请确保满足系统要求，首次运行会自动下载约1GB的Whisper模型文件。

✨ 主要特性

• 基于Whisper的高质量语音识别
• 多语言文本识别
• 支持多种音频格式（mp3、wav、m4a等）
• 符合MCP的工具接口
• 大文件异步处理

📦 安装指南

使用uv（推荐）

使用uv时无需进行特定安装，我们将使用uvx直接运行视频提取服务器：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装FFmpeg

FFmpeg是音频处理所必需的，你可以通过以下多种方式安装：

# Ubuntu或Debian
sudo apt update && sudo apt install ffmpeg

# Arch Linux
sudo pacman -S ffmpeg

# MacOS
brew install ffmpeg

# Windows（使用Chocolatey）
choco install ffmpeg

# Windows（使用Scoop）
scoop install ffmpeg

💻 使用示例

为Claude/Cursor进行配置

在Claude/Cursor设置中添加以下内容：

"mcpServers": {
  "video-extraction": {
    "command": "uvx",
    "args": ["mcp-video-extraction"]
  }
}

可用的MCP工具

1. 视频下载：从支持的平台下载视频
2. 音频下载：从支持平台的视频中提取音频
3. 视频文本提取：从视频中提取文本（下载并转录）
4. 音频文件文本提取：从音频文件中提取文本

📚 详细文档

支持的平台

本服务支持从各种平台下载视频并提取音频，包括但不限于：

• YouTube
• Bilibili
• TikTok
• Instagram
• Twitter/X
• Facebook
• Vimeo
• Dailymotion
• SoundCloud

完整的支持平台列表，请访问 yt-dlp支持的站点。

核心技术

本项目通过MCP工具利用OpenAI的Whisper模型进行音频转文本处理。服务器公开了四个主要工具：

1. 视频下载：从支持的平台下载视频
2. 音频下载：从支持平台的视频中提取音频
3. 视频文本提取：从视频中提取文本（下载并转录）
4. 音频文件文本提取：从音频文件中提取文本

MCP集成

本服务器使用模型上下文协议构建，它提供：

• 向大语言模型公开工具的标准化方式
• 对视频内容和音频文件的安全访问
• 与Claude Desktop等MCP客户端集成

技术栈

• Python 3.10+
• 模型上下文协议（MCP）Python SDK
• yt-dlp（YouTube视频下载）
• openai-whisper（核心音频转文本引擎）
• pydantic

系统要求

• FFmpeg（音频处理必需）
• 至少8GB内存
• 推荐GPU加速（NVIDIA GPU + CUDA）
• 足够的磁盘空间（用于模型下载和临时文件）

配置

该服务可以通过环境变量进行配置：

Whisper配置

• WHISPER_MODEL：Whisper模型大小（tiny/base/small/medium/large），默认值：'base'
• WHISPER_LANGUAGE：转录的语言设置，默认值：'auto'

YouTube下载配置

• YOUTUBE_FORMAT：下载的视频格式，默认值：'bestaudio'
• AUDIO_FORMAT：提取的音频格式，默认值：'mp3'
• AUDIO_QUALITY：音频质量设置，默认值：'192'

存储配置

• TEMP_DIR：临时文件存储位置，默认值：'/tmp/mcp-video'

下载设置

• DOWNLOAD_RETRIES：下载重试次数，默认值：10
• FRAGMENT_RETRIES：片段下载重试次数，默认值：10
• SOCKET_TIMEOUT：套接字超时时间（秒），默认值：30

性能优化提示

1. GPU加速：
   • 安装CUDA和cuDNN
   • 确保安装了PyTorch的GPU版本
2. 调整模型大小：
   • tiny：速度最快，但准确率较低
   • base：速度和准确率平衡
   • large：准确率最高，但需要更多资源
3. 使用SSD存储临时文件以提高I/O性能

注意事项

• 首次运行时需要下载Whisper模型（约1GB）
• 确保有足够的磁盘空间用于临时音频文件
• YouTube视频下载需要稳定的网络连接
• 建议使用GPU以加快音频处理速度
• 处理长视频可能需要较长时间

MCP集成指南

本服务器可与任何兼容MCP的客户端配合使用，例如：

• Claude Desktop
• 自定义MCP客户端
• 其他支持MCP的应用程序

有关MCP的更多信息，请访问 模型上下文协议。

文档

中文文档请参考 README_zh.md

🔧 技术细节

本项目利用OpenAI的Whisper模型进行音频转文本处理，这是核心的音频处理技术。服务器基于模型上下文协议（MCP）构建，通过标准化的方式向大语言模型公开工具，同时保障对视频内容和音频文件的安全访问。技术栈采用Python 3.10+，结合了MCP Python SDK、yt-dlp、openai-whisper和pydantic等工具和库。

📄 许可证

本项目采用MIT许可证。

⚠️ 重要提示

首次运行时，系统会自动下载Whisper模型文件（约1GB），此过程可能需要几分钟到几十分钟，具体取决于网络状况。模型文件将在本地缓存，后续运行无需再次下载。

💡 使用建议

• 确保有足够的磁盘空间用于临时音频文件
• 建议使用GPU以加快音频处理速度
• 处理长视频可能需要较长时间，请耐心等待