Video Fetch MCP

🚀 🎬 Video Fetch MCP

基于 MCP 协议的多平台视频下载服务端，支持 1000+ 视频平台，可通过双模式运行，提供实时进度跟踪等功能。

🚀 快速开始

MCP 协议模式

在你的 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "video-fetch": {
      "command": "npx",
      "args": ["@pickstar-2002/video-fetch-mcp@latest"]
    }
  }
}

REST API 模式

# 启动 REST API 服务器
npx @pickstar-2002/video-fetch-mcp@latest api

# 或者使用已安装的版本
video-fetch-mcp api

✨ 主要特性

• 🎯 多平台支持：基于 yt-dlp，支持 YouTube、哔哩哔哩、抖音、Twitter 等 1000+ 平台。
• 🔄 双模式运行：支持 MCP 协议模式和 REST API 模式。
• 📊 实时进度跟踪：提供下载进度、速度、剩余时间等实时信息。
• 🎵 多格式支持：支持视频下载、音频提取、字幕下载。
• 🛡️ 类型安全：使用 TypeScript 开发，提供完整的类型定义。
• 📝 详细日志：完整的操作日志记录和错误追踪。

📦 安装指南

作为 MCP 服务器使用（推荐）

# 使用 @latest 标签获取最新版本（推荐）
npx @pickstar-2002/video-fetch-mcp@latest

全局安装

npm install -g @pickstar-2002/video-fetch-mcp@latest

本地安装

npm install @pickstar-2002/video-fetch-mcp@latest

💻 使用示例

基础用法

MCP 工具

服务器提供以下 MCP 工具：

• get_video_info：获取视频详细信息

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

• download_video：下载视频文件

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "outputPath": "./downloads",
  "quality": "best",
  "extractAudio": false,
  "downloadSubtitles": true
}

• get_task_status：查询下载任务状态

{
  "taskId": "uuid-task-id"
}

• cancel_task：取消下载任务

{
  "taskId": "uuid-task-id"
}

REST API

• 获取视频信息

curl -X POST http://localhost:8080/api/v1/video/info \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

• 开始下载

curl -X POST http://localhost:8080/api/v1/video/download \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "outputPath": "./downloads",
    "quality": "best"
  }'

• 查看任务状态

curl http://localhost:8080/api/v1/task/{taskId}

📚 详细文档

🌐 支持的平台

• 🎥 YouTube (youtube.com, youtu.be)
• 📺 哔哩哔哩 (bilibili.com)
• 🎵 抖音 (douyin.com)
• 🐦 Twitter/X (twitter.com, x.com)
• 📷 Instagram (instagram.com)
• 📘 Facebook (facebook.com)
• 🎬 Vimeo (vimeo.com)
• 🎮 Twitch (twitch.tv)
• 📱 TikTok (tiktok.com)
• 🔴 Reddit (reddit.com)
• 📺 Dailymotion (dailymotion.com)
• ...以及 1000+ 其他平台

⚙️ 配置选项

环境变量

# 服务端口（默认：8080）
PORT=8080

# 日志级别（默认：info）
LOG_LEVEL=info

# yt-dlp 超时时间（默认：300000ms）
YTDLP_TIMEOUT=300000

下载选项

• quality：视频质量 (best, worst, bestvideo, bestaudio)
• outputTemplate：文件名模板 (默认: %(title)s.%(ext)s)
• extractAudio：是否提取音频
• audioFormat：音频格式 (mp3, aac, wav, flac)
• downloadSubtitles：是否下载字幕
• subtitleLangs：字幕语言列表

🔧 技术细节

疑难解答

常见问题

• ❌ Connection closed 错误：这通常是由于 npx 缓存问题导致的。请按以下顺序尝试解决：
  • 1. 确认使用 @latest 标签（首选方案）

npx @pickstar-2002/video-fetch-mcp@latest

- **2. 锁定到特定版本（备用方案）**

npx @pickstar-2002/video-fetch-mcp@1.0.0

- **3. 清理 npx 缓存（终极方案）**

# 清理 npx 缓存
npx clear-npx-cache

# 或者手动清理
rm -rf ~/.npm/_npx
# Windows 用户使用：rmdir /s %USERPROFILE%\.npm\_npx

# 然后重新运行
npx @pickstar-2002/video-fetch-mcp@latest

• ❌ yt-dlp 未找到：确保系统已安装 Python 和 yt-dlp：

# 安装 yt-dlp
pip install yt-dlp

# 或使用 conda
conda install -c conda-forge yt-dlp

• ❌ 端口被占用：修改端口配置：

PORT=8081 npx @pickstar-2002/video-fetch-mcp@latest api

• ❌ 权限错误：确保输出目录有写入权限：

mkdir -p ./downloads
chmod 755 ./downloads

调试模式

启用详细日志：

LOG_LEVEL=debug npx @pickstar-2002/video-fetch-mcp@latest

开发

本地开发

# 克隆仓库
git clone https://github.com/pickstar-2002/video-fetch-mcp.git
cd video-fetch-mcp

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 启动
npm start

项目结构

video-fetch-mcp/
├── src/
│   ├── services/
│   │   ├── mcp-server-fixed.ts    # MCP 服务器实现
│   │   ├── rest-api-server.ts     # REST API 服务器
│   │   └── ytdlp-service.ts       # yt-dlp 核心服务
│   ├── utils/
│   │   └── logger.ts              # 日志工具
│   ├── types.ts                   # 类型定义
│   ├── config.ts                  # 配置文件
│   └── index.ts                   # 入口文件
├── dist/                          # 编译输出
└── downloads/                     # 默认下载目录

📄 API 文档

REST API 端点

MCP 工具

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库。
2. 创建特性分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m 'Add some amazing feature')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 开启 Pull Request。

📝 更新日志

v1.0.0

• 🎉 初始版本发布。
• ✅ 支持 MCP 协议和 REST API 双模式。
• ✅ 集成 yt-dlp 支持 1000+ 平台。
• ✅ 实时进度跟踪和任务管理。
• ✅ TypeScript 类型安全。

📜 许可证

本项目采用 MIT 许可证。

📞 联系方式

如有问题或建议，欢迎联系： 微信: pickstar_loveXX

⭐ 如果这个项目对你有帮助，请给个 Star！