Video Fetch MCP

🚀 Video Fetch MCP

A multi-platform video download server based on the MCP protocol, supporting over 1000 video platforms.

🚀 Quick Start

MCP Protocol Mode

Add the following to your MCP client configuration file:

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

REST API Mode

# Start the REST API server
npx @pickstar-2002/video-fetch-mcp@latest api

# Or use the installed version
video-fetch-mcp api

✨ Features

• 🎯 Multi-platform Support: Based on yt-dlp, supports over 1000 platforms such as YouTube, Bilibili, Douyin, and Twitter.
• 🔄 Dual-mode Operation: Supports both MCP protocol mode and REST API mode.
• 📊 Real-time Progress Tracking: Provides real-time information on download progress, speed, and remaining time.
• 🎵 Multi-format Support: Supports video download, audio extraction, and subtitle download.
• 🛡️ Type Safety: Developed with TypeScript, providing complete type definitions.
• 📝 Detailed Logs: Complete operation log recording and error tracking.

📦 Installation

As an MCP Server (Recommended)

# Use the @latest tag to get the latest version (recommended)
npx @pickstar-2002/video-fetch-mcp@latest

Global Installation

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

Local Installation

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

💻 Usage Examples

MCP Tools

The server provides the following MCP tools:

get_video_info

Get detailed video information.

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

download_video

Download a video file.

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

get_task_status

Query the status of a download task.

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

cancel_task

Cancel a download task.

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

REST API

Get Video Information

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

Start Download

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

Check Task Status

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

🌐 Supported Platforms

• 🎥 YouTube (youtube.com, youtu.be)
• 📺 Bilibili (bilibili.com)
• 🎵 Douyin (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)
• ...and over 1000 other platforms

⚙️ Configuration Options

Environment Variables

# Service port (default: 8080)
PORT=8080

# Log level (default: info)
LOG_LEVEL=info

# yt-dlp timeout (default: 300000ms)
YTDLP_TIMEOUT=300000

Download Options

• quality: Video quality (best, worst, bestvideo, bestaudio)
• outputTemplate: Filename template (default: %(title)s.%(ext)s)
• extractAudio: Whether to extract audio
• audioFormat: Audio format (mp3, aac, wav, flac)
• downloadSubtitles: Whether to download subtitles
• subtitleLangs: List of subtitle languages

🔧 Troubleshooting

Common Issues

❌ Connection closed Error

This is usually caused by npx cache issues. Please try the following solutions in order:

1. Confirm using the @latest tag (preferred solution)

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

2. Lock to a specific version (alternative solution)

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

3. Clear the npx cache (ultimate solution)

# Clear the npx cache
npx clear-npx-cache

# Or manually clear
rm -rf ~/.npm/_npx
# Windows users use: rmdir /s %USERPROFILE%\.npm\_npx

# Then run again
npx @pickstar-2002/video-fetch-mcp@latest

❌ yt-dlp Not Found

Ensure that Python and yt-dlp are installed on your system:

# Install yt-dlp
pip install yt-dlp

# Or use conda
conda install -c conda-forge yt-dlp

❌ Port in Use

Modify the port configuration:

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

❌ Permission Error

Ensure that the output directory has write permissions:

mkdir -p ./downloads
chmod 755 ./downloads

Debug Mode

Enable detailed logs:

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

🛠️ Development

Local Development

# Clone the repository
git clone https://github.com/pickstar-2002/video-fetch-mcp.git
cd video-fetch-mcp

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Start
npm start

Project Structure

video-fetch-mcp/
├── src/
│   ├── services/
│   │   ├── mcp-server-fixed.ts    # MCP server implementation
│   │   ├── rest-api-server.ts     # REST API server
│   │   └── ytdlp-service.ts       # yt-dlp core service
│   ├── utils/
│   │   └── logger.ts              # Logging tool
│   ├── types.ts                   # Type definitions
│   ├── config.ts                  # Configuration file
│   └── index.ts                   # Entry file
├── dist/                          # Compiled output
└── downloads/                     # Default download directory

📄 API Documentation

REST API Endpoints

MCP Tools

🤝 Contribution

Contributions are welcome! Please follow these steps:

1. Fork this repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

📝 Changelog

v1.0.0

• 🎉 Initial release.
• ✅ Support for both MCP protocol and REST API modes.
• ✅ Integration with yt-dlp to support over 1000 platforms.
• ✅ Real-time progress tracking and task management.
• ✅ Type safety with TypeScript.

📜 License

This project is licensed under the MIT license.

📞 Contact

If you have any questions or suggestions, please contact: WeChat: pickstar_loveXX

⭐ If this project is helpful to you, please give it a Star!