🎬 yt-dlp mcp
强大的MCP服务器,为您的AI代理带来视频平台功能
将yt-dlp与Claude、Dive和其他MCP兼容的AI系统集成。通过自然语言下载视频、提取元数据、获取成绩单等。
✨ 特性
🔍 搜索与发现
- 使用分页搜索YouTube
- JSON或Markdown输出格式
- 按相关性和质量过滤
📊 元数据抽取
- 全面的视频信息
- 频道详细信息和统计数据
- 上传日期、标签、类别
- 无需下载内容
📝 成绩单和字幕
- 下载VTT格式的字幕
- 生成干净的文本记录
- 自动生成字幕
🎥 视频下载
- 分辨率控制(480p-1080p)
- 视频剪辑支持
- 平台无关(YouTube、Facebook等)
- 已保存到下载文件夹
🎵 音频提取
- 最佳音质(M4A/MP3)
- 仅限直接音频下载
- 非常适合播客和音乐
🛡️ 隐私与安全
- 无跟踪或分析
- 通过yt-dlp直接下载
- Zod模式验证
- LLM安全的字符限制
🚀 安装
先决条件
安装yt-dlp 在您的系统上:
Platform · Command
🪟 Windows · winget install yt-dlp
🍎 macOS · brew install yt-dlp
🐧 Linux · pip install yt-dlp
入门指南
将以下配置添加到MCP客户端:```json
{
"mcpServers": {
"yt-dlp": {
"command": "npx",
"args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
}
}
}
### MCP客户端配置
Dive
1. 打开 潜水桌面
1. 点击 **“+添加MCP服务器”**
1. 粘贴上面提供的配置
1. 点击 **“保存”** 你准备好了!
Claude Code
使用Claude Code CLI添加yt-dlp MCP服务器(指南):```bash
claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest
Claude Desktop
添加到您的 claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户:
%APPDATA%\Claude\claude_desktop_config.json - Linux: `~/.config/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"yt-dlp": {
"command": "npx",
"args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
}
}
}
Cursor
首选 `Cursor Settings` -> `MCP` -> `New MCP Server`.使用上面提供的配置。
VS Code / Copilot
通过VS Code CLI安装:```bash
code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'
或者跟随 MCP安装指南 使用上面的标准配置。
Windsurf
跟随 配置MCP指南 使用上面的标准配置。
Cline
跟随 临床MCP配置指南 并使用上面提供的配置。
Warp
首选 Settings · AI · Manage MCP Servers -> + Add 到 添加MCP服务器.使用上面提供的配置。
JetBrains AI Assistant
首选 Settings · Tools · AI Assistant · Model Context Protocol (MCP) -> Add.使用上面提供的配置。
手动安装```bash
npm install -g @kevinwatt/yt-dlp-mcp
______________________________________________________________________
## 🛠️ 可用工具
所有工具都以前缀 `ytdlp_` 以避免与其他MCP服务器的命名冲突。
### 🔍 搜索与发现
Tool · Description
ytdlp_search_videos
使用分页和日期过滤支持搜索YouTube
- **参数**: `query`, `maxResults`, `offset`, `response_format`, `uploadDateFilter`
- **日期筛选器**: `hour`, `today`, `week`, `month`, `year` (可选)
- **退货**:视频列表,包括标题、频道、持续时间、网址
- **支持**:JSON和Markdown格式
### 📝 字幕和文字记录
Tool · Description
ytdlp_list_subtitle_languages
列出视频的所有可用字幕语言
- **参数**: `url`
- **退货**:可用语言、格式、自动生成的状态
ytdlp_download_video_subtitles
下载带有时间戳的VTT格式字幕
- **参数**: `url`, `language` (可选)
- **退货**:原始VTT字幕内容
ytdlp_download_transcript
生成干净的纯文本转录
- **参数**: `url`, `language` (可选)
- **退货**:无时间戳或格式的已清理文本
### 🎥 视频和音频下载
Tool · Description
ytdlp_download_video
将视频下载到下载文件夹
- **参数**: `url`, `resolution`, `startTime`, `endTime`
- **决议**:480p、720p、1080p,最好
- **支持**:视频剪辑
ytdlp_download_audio
仅提取和下载音频
- **参数**: `url`
- **格式**:最优质的M4A/MP3
### 📊 元数据
Tool · Description
ytdlp_get_video_metadata
以JSON格式提取全面的视频元数据
- **参数**: `url`, `fields` (可选数组)
- **退货**:完整的元数据或筛选字段
- **包含**:视图、点赞、上传日期、标签、格式等。
ytdlp_get_video_metadata_summary
获取人类可读的元数据摘要
- **参数**: `url`
- **退货**:带有关键信息的格式化文本
______________________________________________________________________
## 💡 使用示例
### 搜索视频```
"Search for Python programming tutorials"
"Find the top 20 machine learning videos"
"Search for 'react hooks tutorial' and show results 10-20"
"Search for JavaScript courses in JSON format"
获取元数据```
"Get metadata for https://youtube.com/watch?v=..."
"Show me the title, channel, and view count for this video"
"Extract just the duration and upload date"
"Give me a quick summary of this video's info"
### 下载字幕和成绩单```
"List available subtitles for https://youtube.com/watch?v=..."
"Download English subtitles from this video"
"Get a clean transcript of this video in Spanish"
"Download Chinese (zh-Hant) transcript"
下载内容```
"Download this video in 1080p: https://youtube.com/watch?v=..."
"Download audio from this YouTube video"
"Download this video from 1:30 to 2:45"
"Save this Facebook video to my Downloads"
______________________________________________________________________
## 📖 文档
- **API 参考** -详细的工具文档
- **配置** -环境变量和设置
- **Cookie配置** -身份验证和私人视频访问
- **错误处理** -常见错误及解决方法
- **贡献** -如何做出贡献
______________________________________________________________________
## 🔧 配置
### 环境变量```bash
# Downloads directory (default: ~/Downloads)
YTDLP_DOWNLOADS_DIR=/path/to/downloads
# Default resolution (default: 720p)
YTDLP_DEFAULT_RESOLUTION=1080p
# Default subtitle language (default: en)
YTDLP_DEFAULT_SUBTITLE_LANG=en
# Character limit (default: 25000)
YTDLP_CHARACTER_LIMIT=25000
# Max transcript length (default: 50000)
YTDLP_MAX_TRANSCRIPT_LENGTH=50000
Cookie配置
要访问私人视频、年龄限制内容或避免速率限制,请配置Cookie:
> ⚠️ 重要:Cookie身份验证需要安装JavaScript运行时(deno)。使用Cookie时,YouTube使用经过验证的API端点,这些端点需要解决JavaScript挑战。没有deno,下载将失败,并出现“n挑战解决失败”错误。
>
> 安装deno:https://docs.deno.com/runtime/getting_started/installation/```bash
Extract cookies from browser (recommended)
YTDLP_COOKIES_FROM_BROWSER=chrome
Or use a cookie file
YTDLP_COOKIES_FILE=/path/to/cookies.txt
**使用Cookie的MCP配置:**```json
{
"mcpServers": {
"yt-dlp": {
"command": "npx",
"args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
"env": {
"YTDLP_COOKIES_FROM_BROWSER": "chrome"
}
}
}
}
支持的浏览器: brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale
看 Cookie配置指南 有关详细的设置说明。
🏗️ 建筑
构建于
- yt-dlp -视频提取引擎
- MCP-SDK -模型上下文协议
- 萨德 -TypeScript第一模式验证
- TypeScript -类型安全和开发人员经验
主要特点
- ✅ 类型安全:具有严格模式的完整TypeScript
- ✅ 验证输入:用于运行时验证的Zod模式
- ✅ 字符限制:自动截断以防止上下文溢出
- ✅ 工具注释:只读、破坏性、幂等提示
- ✅ 错误指导:LLM的可操作错误消息
- ✅ 模块化设计:明确区分关注点
📊 响应格式
JSON格式
非常适合程序化处理:```json
{
"total": 50,
"count": 10,
"offset": 0,
"videos": [...],
"has_more": true,
"next_offset": 10
}
### Markdown格式
人类可读显示器:```markdown
Found 50 videos (showing 10):
1. **Video Title**
📺 Channel: Creator Name
⏱️ Duration: 10:30
🔗 URL: https://...
🔒 隐私和安全
- 无追踪:直接下载,无需分析
- 输入验证:Zod模式防止注入
- URL验证:严格的URL格式检查
- 字符限制:防止上下文溢出攻击
- 默认情况下为只读:大多数工具不会修改系统状态
🤝 贡献
欢迎投稿!请查看我们的 贡献指南.
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
📝 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- yt-dlp -令人惊叹的视频提取工具
- Anthropic -对于模型上下文协议
- 潜水 -MCP兼容AI平台
📚 相关项目
- MCP服务器 -官方MCP服务器实施
- yt-dlp -命令行视频下载器
- 潜水桌面 -AI代理平台
⬆ 返回页首
