yt-dlp-mcp

🎬 yt-dlp-mcp

✨ 功能

🚀 安装

前置条件

在系统上安装 yt-dlp：

开始使用

将以下配置添加到 MCP 客户端：

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

MCP 客户端配置

claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'

手动安装

npm install -g @kevinwatt/yt-dlp-mcp

🛠️ 可用工具

所有工具均以 ytdlp_ 为前缀，以避免与其他 MCP 服务发生命名冲突。

🔍 搜索与发现

📝 字幕与文字稿

🎥 视频与音频下载

💬 评论

💡 使用示例

搜索视频

"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"

获取评论

"Get the top 20 comments for https://youtube.com/watch?v=..."
"Get comments as threaded JSON for this video"
"Extract comments as markdown_tree so the reply branches stay intact"
"Get newest comments with maxDepth 1 and maxRepliesPerThread 0"
"Summarize comments in threaded view"

下载字幕和转录文本

"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 配置 - 身份验证和私有视频访问
• 错误处理 - 常见错误及解决方案
• 贡献指南 - 如何参与贡献

🔧 配置

环境变量

# 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

完整列表请参阅配置指南。

代理和 yt-dlp 配置文件

所有工具都会读取你的 yt-dlp 配置文件（~/.config/yt-dlp/config），因此其中设置的任何 --proxy、--cookies 或其他选项都会自动生效。对于无法向服务进程传递环境变量的 MCP 客户端来说，这是唯一可用的方式。

以下选项互为替代——只设置你需要的选项：

支持的代理协议：http、https、socks4、socks5、socks5h。

YTDLP_IGNORE_CONFIG=1 并不等同于直接回退到 0.9.x。搜索、元数据和评论工具始终会读取配置文件，因此此设置也会阻止它们读取配置文件。

使用代理的 MCP 配置：

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

如果你的 MCP 客户端无法向服务传递环境变量，请改为将选项写入 ~/.config/yt-dlp/config——每个工具都会读取该文件：

--proxy socks5://127.0.0.1:1080
--cookies /path/to/cookies.txt

注意：你的配置文件也会应用于下载。更改输出格式的选项（-x、--remux-video、--recode-video）会改变下载工具生成的内容；工具会报告 yt-dlp 实际写入的文件，因此报告的名称仍然准确。输出位置选项（-o、-P）不会生效，因为工具始终会在命令行中传入绝对路径的 --output，而它的优先级更高。

注意：yt-dlp 配置文件可以包含用于执行命令的选项（--exec、--postprocessor-args、--ffmpeg-location）。现在，这些选项也会在调用工具时运行，包括由 AI 助手触发的调用。如果你希望服务完全忽略配置文件，请设置 YTDLP_IGNORE_CONFIG=1。

Cookie 配置

要访问私人视频、年龄限制内容或避免触发速率限制，请配置 Cookie：

⚠️ 重要：Cookie 身份验证要求安装 JavaScript 运行时（deno）。使用 Cookie 时，YouTube 会使用需要 JavaScript 挑战求解的已验证 API 端点。如果没有 deno，下载会失败并报错："n challenge solving failed"。

安装 deno：https://docs.deno.com/runtime/getting_started/installation/

# Extract cookies from browser (recommended)
YTDLP_COOKIES_FROM_BROWSER=chrome

# Or use a cookie file
YTDLP_COOKIES_FILE=/path/to/cookies.txt

使用 Cookie 的 MCP 配置：

{
  "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 - Model Context Protocol
• Zod - TypeScript 优先的模式验证
• TypeScript - 类型安全和开发者体验

主要功能

• ✅ 类型安全：全面使用 TypeScript 并启用严格模式
• ✅ 输入验证：使用 Zod 模式进行运行时验证
• ✅ 字符数限制：自动截断，防止上下文溢出
• ✅ 工具注解：readOnly、destructive、idempotent 提示
• ✅ 错误指引：为 LLM 提供可操作的错误消息
• ✅ 模块化设计：清晰划分关注点

📊 响应格式

JSON 格式

适合以编程方式处理：

{
  "total": 50,
  "count": 10,
  "offset": 0,
  "videos": [...],
  "has_more": true,
  "next_offset": 10
}

Markdown 格式

便于人类阅读：

Found 50 videos (showing 10):

1. **Video Title**
   📺 Channel: Creator Name
   ⏱️  Duration: 10:30
   🔗 URL: https://...

评论 Markdown 树

回复上下文很重要时，适用于 LLM 分析：

# AI-Ready Comment Threads

source_title: "Sample Video"
comments_detected: 20
root_threads: 6
reply_comments: 14

## Threads

### Thread 1

- comment_id: "abc123"
  parent_id: "root"
  depth: 0
  reply_count: 2
  text:
    | Root comment text
  - comment_id: "reply456"
    parent_id: "abc123"
    depth: 1
    reply_count: 0
    text:
      | Reply text

评论限制

YouTube 评论提取支持完整的提取器元组：

youtube:comment_sort=<sort>;max_comments=<total>,<parents>,<replies>,<repliesPerThread>,<depth>

示例：

• 默认行为：maxComments=20 会生成 max_comments=20,20,20,20,2
• 仅提取根评论：maxDepth=1、maxRepliesPerThread=0
• 限制分支：maxReplies=40、maxRepliesPerThread=5、maxDepth=2

🔒 隐私与安全

• 无跟踪：直接下载，不进行分析
• 输入验证：Zod 模式可防止注入
• URL 验证：严格检查 URL 格式
• 字符限制：防止上下文溢出攻击
• 默认只读：大多数工具不会修改系统状态

🤝 参与贡献

欢迎贡献！请查看我们的贡献指南。

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

📝 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• yt-dlp - 出色的视频提取工具
• Anthropic - 提供 Model Context Protocol
• Dive - 兼容 MCP 的 AI 平台

📚 相关项目

• MCP Servers - 官方 MCP 服务实现
• yt-dlp - 命令行视频下载器
• Dive Desktop - AI Agent 平台