Video Fetch MCP

🎬 Video Fetch MCP

🚀 基于 MCP 协议的多平台视频下载服务端，支持 1000+ 视频平台

✨ 特性

🎯 多平台支持：基于 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 客户端配置文件中添加：

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

🔧 IDE 配置

Cursor

在 .cursor/mcp_config.json 中添加：

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

WindSurf

在 .windsurf/mcp_config.json 中添加：

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

CodeBuddy

在 .codebuddy/mcp_config.json 中添加：

{
  "mcpServers": {
    "video-fetch": {
      "command": "npx",
      "args": ["@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 端点

方法	端点	描述
GET	`/api/v1/health`	健康检查
POST	`/api/v1/video/info`	获取视频信息
POST	`/api/v1/video/download`	开始下载
GET	`/api/v1/task/:taskId`	查看任务状态
DELETE	`/api/v1/task/:taskId`	取消任务
GET	`/api/v1/tasks`	列出所有任务
GET	`/api/v1/platforms`	获取支持的平台

MCP 工具

工具名	描述	参数
`get_video_info`	获取视频信息	`url`
`download_video`	下载视频	`url`, `outputPath`, `quality`, etc.
`get_task_status`	查看任务状态	`taskId`
`cancel_task`	取消任务	`taskId`
`list_tasks`	列出所有任务	-

🤝 贡献

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

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

📝 更新日志

v1.0.0

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

📜 许可证

本项目采用 MIT 许可证。

📞 联系方式

如有问题或建议，欢迎联系：

微信: pickstar_loveXX

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

Install Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Enables downloading videos from 1000+ platforms including YouTube, Bilibili, TikTok, and Twitter using yt-dlp. Supports both MCP protocol and REST API modes with real-time progress tracking, multiple formats, and subtitle downloads.

Related MCP Servers

YouTube MCP Server
anaisbetts
A
security
A
license
A
quality
Uses yt-dlp to download subtitles from YouTube and connects it to claude.ai via Model Context Protocol.
Last updated -
1
883
415
JavaScript
MIT License
YouTube MCP Server
kevinwatt
-
security
A
license
-
quality
Connects 'yt-dlp' with LLMs via the Model Context Protocol, allowing users to download YouTube content and integrate it with Dive and other MCP-compatible LLMs.
Last updated -
2
169
57
TypeScript
MIT License
TikTok MCP
Seym0n
A
security
A
license
A
quality
A MCP Server for TikTok videos that allows you to get video subtitles and post details, such as the number of likes, hashtags, and publishing time.
Last updated -
3
1
82
JavaScript
MIT License
Video Content Summarization MCP Server
fakad
-
security
A
license
-
quality
Extracts content from multiple video platforms (Douyin, Bilibili, Xiaohongshu, Zhihu) and generates intelligent knowledge graphs with OCR text recognition capabilities.
Last updated -
1
Python
MIT License

View all related MCP servers

🎬 Video Fetch MCP

✨ 特性

📦 安装

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

全局安装

本地安装

🚀 快速开始

MCP 协议模式

REST API 模式

🔧 IDE 配置

Cursor

WindSurf

CodeBuddy

📖 使用方法

MCP 工具

get_video_info

download_video

get_task_status

cancel_task

REST API

获取视频信息

开始下载

查看任务状态

🌐 支持的平台

⚙️ 配置选项

环境变量

下载选项

🔧 疑难解答

常见问题

❌ Connection closed 错误

❌ yt-dlp 未找到

❌ 端口被占用

❌ 权限错误

调试模式

🛠️ 开发

本地开发

项目结构

📄 API 文档

REST API 端点

MCP 工具

🤝 贡献

📝 更新日志

v1.0.0

📜 许可证

📞 联系方式

Tools

Related MCP Servers

YouTube MCP Server

YouTube MCP Server

TikTok MCP

Video Content Summarization MCP Server

New MCP Servers

MCP directory API

`get_video_info`

`download_video`

`get_task_status`

`cancel_task`