一个用于使用 yt-dlp 下载视频和流的模型上下文协议（MCP）服务器。该服务器使兼容 MCP 的客户端（如 Claude Desktop）能够从 YouTube 和 1000+ 支持的网站下载视频、提取音频、下载字幕以及捕获直播流。
本项目基于 yt-dlp 团队的杰出工作构建。yt-dlp 是一个功能丰富的命令行音视频下载器，支持数千个网站。有关 yt-dlp 的更多信息，请访问其 GitHub 仓库 或 wiki。
Related MCP server: MCP YouTube Downloader
视频下载：从 YouTube 和 1000+ 支持的网站下载视频
流下载：捕获直播流和 HLS/m3u8 流
视频信息：无需下载即可获取元数据
格式列表：列出视频的所有可用格式
搜索：通过 yt-dlp 提取器直接搜索视频
音频提取：仅下载音频并进行格式转换（MP3、M4A、WAV、FLAC）
字幕：下载多种语言的字幕
播放列表支持：下载完整或部分播放列表
Node.js 18+
yt-dlp 已安装，并且与服务器位于同一目录（或位于 PATH 中）
从 nodejs.org 下载并安装 Node.js 18+。
验证安装：
node --version
npm --version我们提供了设置脚本，可自动将最新的 yt-dlp 下载到正确的目录。
Windows：
双击 setup.bat 或在命令提示符中运行：
setup.batLinux / macOS：
chmod +x setup.sh
./setup.sh该脚本将：
检测您的操作系统
下载最新的 yt-dlp 二进制文件
将其放置在与 MCP 服务器相同的目录中
验证安装
如果您希望手动安装 yt-dlp：
Windows：
从 最新版本 下载 yt-dlp.exe
将 yt-dlp.exe 放置在与 MCP 服务器相同的目录中
macOS：
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
chmod a+rx /usr/local/bin/yt-dlpLinux：
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlpPython（所有平台）：
pip install yt-dlp有关更多安装选项，请参阅 yt-dlp 安装指南。
git clone https://github.com/timyee22/yt-dlp-MCP.git
cd yt-dlp-MCPnpm install将服务器添加到您的 MCP 客户端配置中：
Claude Desktop（Windows）：
编辑 %APPDATA%\Claude\settings.json：
{
"mcpServers": {
"yt-dlp": {
"command": "node",
"args": ["C:\\path\\to\\yt-dlp-MCP\\index.js"]
}
}
}Claude Desktop（macOS/Linux）：
编辑 ~/Library/Application Support/Claude/settings.json（macOS）或相应的配置路径：
{
"mcpServers": {
"yt-dlp": {
"command": "node",
"args": ["/path/to/yt-dlp-MCP/index.js"]
}
}
}重要： 确保 yt-dlp.exe（Windows）或 yt-dlp（macOS/Linux）满足以下任一条件：
与 index.js 位于同一目录
或位于系统 PATH 中
添加配置后，重启 Claude Desktop 以加载新的 MCP 服务器。
配置完成后，您可以要求 Claude：
“下载这个 YouTube 视频：[URL]”
“仅将此视频的音频下载为 MP3”
“获取此视频的信息，无需下载”
“列出此视频的所有可用格式”
“在 YouTube 上搜索关于 [主题] 的视频”
“下载此视频的西班牙语字幕”
从 URL 下载视频。
参数：
url（必需）：视频 URL
outputDir：输出目录（默认：当前目录）
format：格式选择（默认：“best”）
quality：视频质量（例如，“1080p”、“720p”）
audioOnly：仅下载音频（默认：false）
audioFormat：提取的音频格式（默认：“mp3”）
subtitles：下载字幕（默认：false）
subtitleLangs：字幕语言（默认：“en”）
playlistStart/playlistEnd：播放列表范围
noPlaylist：仅下载单个视频（默认：false）
additionalArgs：额外的 yt-dlp 参数
示例：
下载 YouTube 视频：
{
"url": "https://www.youtube.com/watch?v=...",
"quality": "1080p",
"subtitles": true
}仅下载音频：
{
"url": "https://www.youtube.com/watch?v=...",
"audioOnly": true,
"audioFormat": "mp3"
}下载直播流或 HLS 流。
参数：
url（必需）：流 URL
outputDir：输出目录
duration：捕获时长（秒）
format：格式偏好（默认：“best”）
outputName：自定义输出文件名
hlsUseMpegts：对 HLS 使用 MPEG-TS（默认：true）
additionalArgs：额外参数
获取视频元数据，无需下载。
参数：
url（必需）：视频 URL
flatPlaylist：更快的播放列表信息（默认：false）
列出 URL 的所有可用格式。
参数：
url（必需）：视频 URL
使用 yt-dlp 提取器搜索视频。
参数：
query（必需）：搜索查询
extractor：搜索提取器前缀（默认：“ytsearch10”）
getInfo：获取详细信息（默认：true）
示例：
{
"query": "programming tutorials",
"extractor": "ytsearch5"
}将 yt-dlp 更新到最新版本。
yt-dlp 支持 1000+ 个网站，包括：
YouTube
Twitch
Vimeo
Twitter/X
TikTok
SoundCloud
以及更多……
有关完整列表，请参阅 yt-dlp 支持的网站。
确保 yt-dlp.exe（Windows）或 yt-dlp（macOS/Linux）与服务器位于同一目录或位于 PATH 中
在 Windows 上，您可能需要将目录添加到 PATH 环境变量中
确保已安装 Node.js 18+：node --version
确保已安装依赖：npm install
某些视频可能没有请求的格式。使用 list_formats 查看可用选项
YouTube 可能限制某些格式。尝试不同的质量设置
Unlicense
Download a live stream or m3u8/HLS stream using yt-dlp.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL of the stream to download | |
| format | No | Stream format preference | best |
| duration | No | Duration in seconds to capture (for live streams) | |
| outputDir | No | Directory to save the stream (default: current directory) | |
| outputName | No | Output filename template (without extension) | |
| hlsUseMpegts | No | Use MPEG-TS container for HLS streams | |
| additionalArgs | No | Additional yt-dlp arguments (space-separated) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only restates the action ('Download') without mentioning any consequences such as prolonged execution for live streams, resource usage, or dependency on ffmpeg. This is a significant gap for a streaming download tool.
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 sentence that is front-loaded with the core action and target. It is concise with no wasted words, making it easy to scan. It could be slightly longer to include behavioral context, but as written it is efficient.
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 7 parameters, no annotations, and no output schema, the description is too minimal. It does not explain how to handle live streams (e.g., needing a duration to stop capture) or the meaning of advanced options like additionalArgs. An agent may struggle to call this tool correctly without additional context.
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?
The description does not mention any parameters, but the input schema provides descriptions for all 7 parameters with 100% coverage. The schema already explains fields like duration and outputName, so the baseline of 3 is appropriate. The description adds no extra meaning beyond the schema.
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 states a clear action ('Download') and a specific target ('a live stream or m3u8/HLS stream'), and mentions the underlying tool yt-dlp. It distinguishes itself from sibling tools like download_video by specifying stream types, though it does not explicitly name that sibling. The purpose is immediately understandable.
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 implies usage for live or HLS streams, which gives some guidance. However, it provides no explicit 'when to use this vs. alternatives' or exclusions, leaving the agent to infer that download_video is for regular videos. The guidance is present but implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a video from a URL using yt-dlp. Supports YouTube and many other sites.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL of the video to download | |
| format | No | Video format to download (e.g., 'best', 'worst', 'bestvideo+bestaudio', 'mp4', 'webm') | best |
| quality | No | Video quality (e.g., '1080p', '720p', '480p') | |
| audioOnly | No | Download audio only (extract audio) | |
| outputDir | No | Directory to save the downloaded video (default: current directory) | |
| subtitles | No | Download subtitles if available | |
| noPlaylist | No | Download only the video, not the playlist | |
| audioFormat | No | Audio format for audio-only downloads (e.g., 'mp3', 'm4a', 'wav', 'flac') | mp3 |
| playlistEnd | No | Playlist item to end at | |
| playlistStart | No | Playlist item to start at | |
| subtitleLangs | No | Subtitle languages to download (e.g., 'en,es,de') | en |
| additionalArgs | No | Additional yt-dlp arguments (space-separated) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says it downloads a video using yt-dlp and supports many sites. It does not mention whether downloads are synchronous, how long they might take, what the output is, error handling, or any side effects. This is minimal for a tool with no annotation support.
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 concise, using two short sentences with no fluff. It front-loads the primary action and intent, and the site support note is brief. It earns a 4 because it is well-structured and to the point, though it sacrifices depth for brevity.
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 12 parameters, no output schema, and no annotations, the description is inadequate. It does not explain what happens after download (return value, file path, errors), does not mention the option to extract audio or subtitles, and lacks any guidance on playlist handling or format selection. An agent given only this description would be under-informed for complex use cases.
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?
The input schema has 100% description coverage, so all parameters are documented in the schema itself. The tool description adds no additional meaning beyond mentioning yt-dlp, which implies behavior but not parameter usage. Per baseline guidance, a score of 3 is appropriate when schema carries the parameter documentation.
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 states a clear verb ('download') and resource ('video from a URL'), and identifies the underlying tool (yt-dlp). It also notes broad site support ('YouTube and many other sites'), which gives context. However, it does not distinguish this tool from its sibling 'download_stream', so the agent cannot tell them apart without additional investigation.
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?
There is no guidance on when to use this tool versus 'download_stream' or other siblings. The description only mentions broad site support, but does not state conditions, prerequisites, or when not to use it. An agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about a video or stream URL without downloading it.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to get information about | |
| flatPlaylist | No | Get flat playlist info (faster, less detail) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It only states the action and that it doesn't download; it omits any details about side effects, rate limits, error behavior, or return format. The lack of an output schema compounds this, leaving the agent unaware of what information is actually returned.
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 clear sentence with no redundant words. It delivers the core purpose and a key constraint ('without downloading') in the least space possible, making it concise and well-structured.
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 no output schema and no annotations, the description is too vague. It says 'information' without specifying what fields are returned (e.g., title, duration, formats). An agent cannot predict the output structure or know if it's suitable for its task. It also omits any caveats (e.g., network requirements, playlist behavior). This is a significant gap given the tool's informational purpose.
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 100%, so both url and flatPlaylist are documented in the schema. The tool description adds no extra parameter context beyond that, which is acceptable given the schema already covers semantics. This matches the baseline for full schema coverage.
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 action ('get information') and the resource ('video or stream URL'), and explicitly distinguishes from download tools with 'without downloading it.' This is a specific, unambiguous statement that differentiates it from sibling tools like download_video and download_stream.
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 phrase 'without downloading it' implies use when metadata is needed without fetching content, but no explicit contrast with alternatives (e.g., list_formats or search_videos) is given. There is no when-not-to-use guidance, so the agent must infer the intended usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available formats for a video URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to list formats for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The verb 'list' implies a read-only, non-destructive operation, which is useful. However, it doesn't disclose whether a network request is made, what the output format looks like (e.g., array of format objects, metadata fields), or potential error conditions (invalid URL, unsupported site). This is adequate for a simple read tool but not rich.
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, clear sentence with no wasted words. It front-loads the key action ('List') and immediately names the target resource. For a tool with one parameter and a straightforward purpose, this is appropriately concise.
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?
The tool has a single parameter and a simple purpose, so the description is largely sufficient to invoke it correctly. However, with no output schema and no mention of what 'formats' means or the return structure (e.g., a list of format objects with resolution, codec, etc.), an agent may be uncertain what to expect. Since annotations are absent and the description doesn't compensate for the missing output schema, it leaves a small but real gap.
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 100%, with the 'url' parameter already described as 'The URL to list formats for'. The description adds no additional meaning beyond calling it a 'video URL', which is essentially the same. Since the schema fully documents the parameter, the baseline of 3 is appropriate; the description does not compensate or expand on any parameter behavior.
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 states a specific verb ('List') and resource ('all available formats for a video URL'). This clearly distinguishes it from siblings like download_video or download_stream, which perform downloads, and from get_video_info, which likely returns different metadata. An agent can easily tell what this tool does and when it's the right one.
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 gives no guidance on when to use this tool versus alternatives. It doesn't mention typical workflows (e.g., listing formats before choosing a download stream), nor does it advise against using it in certain situations. With multiple sibling tools available, the absence of any contextual routing leaves the agent to infer usage on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for videos using yt-dlp's extractors.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (e.g., 'ytsearch5:music video' for 5 results on YouTube) | |
| getInfo | No | Get detailed info for each result | |
| extractor | No | Site extractor prefix (e.g., 'ytsearch', 'ytsearch5') | ytsearch10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It does not state whether the search is read-only, whether it has side effects, or what the output looks like. It only mentions the use of yt-dlp extractors, which is a minor detail but not sufficient for a tool with zero annotations.
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, concise sentence that gets to the point. It is appropriately brief, but it could arguably include more useful details without becoming verbose. It is not bloated, but the brevity comes at the cost of missing behavioral context.
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?
With no output schema and no additional description, the tool lacks a clear statement of return value structure. The description is minimal and does not mention what the search results will look like or how the extractor parameter affects results. It is adequate for a simple search tool, but leaves gaps in expectations.
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 100%, meaning the schema already documents each parameter. The description adds no extra meaning beyond what the schema provides. The baseline of 3 applies because the schema handles the parameter semantics adequately, though the description does not enhance them.
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 action ('Search for videos') and the mechanism ('using yt-dlp's extractors'). It is specific enough to differentiate from sibling tools like download_video or get_video_info, which involve retrieval or actions on specific videos rather than searching.
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 implies usage for searching videos, but does not explicitly state when to prefer this over alternatives or mention any exclusions. The differentiation from sibling tools is not articulated, so an agent must infer the intended context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update yt-dlp to the latest version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing effects. It indicates a mutation ('Update') but omits any side effects: whether it requires internet, modifies the local installation, may fail if not installed, or what happens if already up-to-date. This is a significant gap for a tool that changes system state.
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 leads with the action and resource. There is no wasted wordage, and it is immediately scannable. It earns a top score for conciseness.
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 simplicity (no parameters, no output schema, low complexity), the description covers the core behavior. However, it could briefly mention that the update requires internet connectivity or that it will fetch and install the latest release, which would round out the context. Overall, it is adequate but not exhaustive.
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?
The tool has zero parameters, so there is nothing for the description to explain about parameters. Per the calibration baseline for 0-parameter tools, a score of 4 is appropriate since the description is not missing any parameter documentation.
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 states a specific verb ('Update') and a precise resource ('yt-dlp') with the goal ('to the latest version'). It clearly distinguishes this tool from all siblings, which handle downloading, searching, or metadata retrieval. The purpose is immediately unambiguous.
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 its siblings. There is no mention of prerequisites (e.g., yt-dlp being installed, network access) or conditions that would trigger an update. The description gives no context for when an agent should select this tool—only what it does.
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.
v0.1.0download_streamdownload_videoget_video_infolist_formatssearch_videosupdate_yt_dlpScored across 6 tools
Each tool targets a distinct action: updating the tool, downloading videos, downloading streams, fetching metadata, listing formats, and searching. There is no overlap between download_video and download_stream (explicitly split by content type), and get_video_info/list_formats serve separate informational purposes.
All tool names follow a consistent snake_case verb_noun pattern: update, download, get, list, search. The verbs clearly indicate the action and the nouns specify the target, making the convention uniform and predictable.
With 6 tools, the server is well-scoped for a yt-dlp wrapper. Each tool covers a core functionality (update, video download, stream download, info retrieval, format listing, search) without redundancy or bloat, fitting neatly in the typical 3-15 tool range.
The tool set covers the essential lifecycle for video retrieval: searching, inspecting (info/formats), and downloading (video/stream). Minor gaps exist, such as playlist downloads or extracting audio, but agents can likely work around these via download options, so the surface is adequate for most primary workflows.
Download YouTube videos and clips as MP4 or MP3/AAC, and look up video metadata.
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
YouTube transcripts, search, channel browsing, and playlists for AI agents via MCP.
SubDownload exposes YouTube as an MCP-native data source. Connect via OAuth and your AI agent can summarize videos, fetch full transcripts (even for videos with no captions, via AI ASR), search across channels, and save everything into a private knowledge base. Works with Claude, ChatGPT, Cursor, and 40+ MCP clients. Free credits on signup, no card required.
