This MCP server converts video and audio content to text transcriptions using OpenAI Whisper AI.
Capabilities:
Download videos from YouTube, Bilibili, and other platforms using yt-dlp
Extract audio from videos and convert to speech-recognition-ready formats using ffmpeg
Transcribe speech to text using configurable OpenAI Whisper models (tiny, base, small, medium, large)
Process video URLs (via video_to_text tool) or direct audio URLs (via voice_to_text tool)
Output transcriptions in multiple formats: plain text (.txt), JSON (.json), SRT subtitles (.srt), VTT subtitles (.vtt)
Support multi-language transcription with language specification (e.g., 'en', 'zh', 'ja')
Return transcription previews and local file paths for saved transcriptions
Provide error handling and detailed logging for troubleshooting
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Video to Text MCP Server transcribe https://www.youtube.com/watch?v=dQw4w9WgXcQ into srt format"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
一个基于 Model Context Protocol (MCP) 的服务器，用于下载视频、提取音频并将语音转换为文本。
从 YouTube 或其他支持的平台下载视频（使用 yt-dlp）
提取音频并转换为适合语音识别的格式（使用 ffmpeg）
使用 OpenAI Whisper 将音频转换为文本
支持多种输出格式：纯文本 (.txt)、JSON (.json)、SRT (.srt)、VTT (.vtt)
从音频 URL 直接下载音频并转换为文本
返回转录文本的本地文件路径
Related MCP server: Video Transcriber MCP Server
在使用此 MCP 服务器之前，需要安装以下依赖：
用于下载视频的工具。
# macOS (使用 Homebrew)
brew install yt-dlp
# 其他平台
pip install yt-dlp用于音频提取和转换的工具。
# macOS (使用 Homebrew)
brew install ffmpeg
# Ubuntu/Debian
sudo apt-get install ffmpeg
# 其他平台请参考官方文档用于语音转文本的 AI 模型。
pip install openai-whisperWhisper 需要 Python 3.8 或更高版本。安装后，Whisper 会自动下载所需的模型文件（首次运行时会下载 base 模型）。
克隆或复制此项目到本地
安装 Node.js 依赖：
cd video-to-text-mcp
npm install
npm run build在 Claude Desktop 或其他 MCP 客户端中配置此服务器：
编辑 ~/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
用于下载视频、提取音频并转换为文本。
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"
}用于从音频 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 buildnpm run devnpm testnpm run debugMCP SDK: @modelcontextprotocol/sdk
类型检查: TypeScript
参数验证: Zod
视频下载: yt-dlp（通过子进程调用）
音频处理: ffmpeg（通过子进程调用）
语音识别: OpenAI Whisper（通过子进程调用）
临时文件: 处理过程中会创建临时文件，处理完成后不会自动清理。临时文件存储在系统的临时目录中。
网络依赖: 需要网络连接以下载视频和 Whisper 模型（首次运行）。
处理时间: 视频下载和语音识别可能需要较长时间，取决于视频长度和系统性能。
存储空间: 需要足够的磁盘空间存储视频、音频和转录文件。
"Command not found: yt-dlp"
确保 yt-dlp 已正确安装并在 PATH 中
尝试运行 which yt-dlp 确认
"Command not found: ffmpeg"
确保 ffmpeg 已正确安装并在 PATH 中
尝试运行 which ffmpeg 确认
"Command not found: whisper"
确保 OpenAI Whisper 已安装：pip install openai-whisper
尝试运行 whisper --help 确认
Whisper 模型下载失败
检查网络连接
手动下载模型：whisper --model base --language en example.mp3
内存不足
处理大型视频时可能需要大量内存
考虑使用较小的 Whisper 模型（如 tiny 或 base）
所有处理日志输出到 stderr，可以在 MCP 客户端中查看。
ISC
Download a video from URL, extract audio, transcribe to text, and save locally
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| outputFormat | No | txt | |
| language | No | Language code for transcription (e.g., 'en', 'zh') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states what the tool does, not how it behaves. It mentions 'save locally' but doesn't disclose where files are saved, file naming, permissions needed, rate limits, error handling, or what 'extract audio' entails technically.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality without unnecessary words. Every phrase ('download a video from URL', 'extract audio', 'transcribe to text', 'save locally') directly contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral aspects like file handling, error cases, performance, or output structure, which are critical for an AI agent to use this tool correctly in complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only 'language' has a description), but the description adds no parameter-specific information beyond what's in the schema. It implies 'url' is for video download but doesn't detail supported formats or constraints. Baseline 3 is appropriate as the schema provides some coverage, but the description doesn't compensate for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific sequence of actions: download video from URL, extract audio, transcribe to text, and save locally. It uses concrete verbs and distinguishes from the sibling 'voice_to_text' by specifying video as the input source rather than voice/audio.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling 'voice_to_text' or other alternatives. The description implies usage for video-to-text conversion but doesn't specify prerequisites, constraints, or comparative contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download an audio file from URL and transcribe to text
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| outputFormat | No | txt | |
| language | No | Language code for transcription (e.g., 'en', 'zh') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions downloading and transcribing but omits critical details like rate limits, authentication needs, file size constraints, error handling, or output behavior. This leaves significant gaps for a tool that performs external operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It is front-loaded and appropriately sized for its purpose, with no wasted information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (external download and transcription), lack of annotations, no output schema, and incomplete parameter documentation, the description is insufficient. It doesn't cover behavioral aspects, output details, or usage context, making it inadequate for safe and effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only 'language' has a description), so the description must compensate. It implies the 'url' parameter by mentioning 'audio file from URL' and hints at transcription output, but doesn't explain 'outputFormat' or 'language' beyond the schema. The description adds minimal value, meeting the baseline for low coverage without fully addressing the gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('download' and 'transcribe') and resources ('audio file from URL' to 'text'). It distinguishes from the sibling 'video_to_text' by specifying audio rather than video. However, it doesn't explicitly mention the sibling differentiation, keeping it at a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'video_to_text' or other transcription methods. It lacks context about prerequisites, limitations, or typical use cases, offering only a basic functional statement without usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
voice_to_textvideo_to_textScored across 2 tools
The two tools have distinct primary purposes: video_to_text handles video files with audio extraction, while voice_to_text handles audio files directly. However, there is some functional overlap in the transcription step, which could cause minor confusion if an agent needs to transcribe audio from a video but chooses the wrong tool. The descriptions help clarify the difference.
Both tools follow a consistent snake_case naming pattern with a clear 'source_to_text' structure (video_to_text and voice_to_text). This makes them predictable and easy to understand, with no deviations in style or convention across the set.
With only 2 tools, the server feels thin for a video-to-text domain, as it lacks operations for managing transcripts (e.g., editing, saving in different formats) or handling video/audio metadata. While the core functionality is covered, the set is borderline minimal and may limit agent workflows.
The tools cover the basic transcription process from video and audio sources, but there are notable gaps: no tools for updating, deleting, or listing transcripts, and no support for batch processing or different output formats. This could lead to dead ends in more complex agent tasks, though simple transcription needs are met.
Any video URL to LLM-ready transcript. ASR built in, no captions needed. TikTok, X, TED and more.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Fetch transcripts, subtitles, chapters, metadata and frames from YouTube and 10+ video platforms
Transcribe YouTube via Whisper. Summaries, chapters, semantic-search across your corpus.
