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！