Skip to main content
Glama

🎬 Video Fetch MCP

npm version License: MIT Node.js Version TypeScript

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

✨ 特性

  • 🎯 多平台支持:基于 yt-dlp,支持 YouTube、哔哩哔哩、抖音、Twitter 等 1000+ 平台

  • 🔄 双模式运行:支持 MCP 协议模式和 REST API 模式

  • 📊 实时进度跟踪:提供下载进度、速度、剩余时间等实时信息

  • 🎵 多格式支持:支持视频下载、音频提取、字幕下载

  • 🛡️ 类型安全:使用 TypeScript 开发,提供完整的类型定义

  • 📝 详细日志:完整的操作日志记录和错误追踪

Related MCP server: YouTube MCP Server

📦 安装

作为 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

列出所有任务

-

🤝 贡献

欢迎贡献代码!请遵循以下步骤:

  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!

Available Tools

5 tools
cancel_taskC

取消下载任务

ParametersJSON Schema
NameRequiredDescriptionDefault
taskIdYes任务ID

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the action (cancel) but lacks behavioral details: whether cancellation is reversible, if it requires specific permissions, what happens to partial downloads, or error conditions. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single phrase '取消下载任务', which is extremely concise and front-loaded with the core action. There is zero waste or redundancy, making it efficient for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a mutation operation to cancel tasks), lack of annotations, no output schema, and minimal description, it's incomplete. It doesn't cover behavioral aspects, error handling, or output expectations, leaving gaps for safe and effective use by an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the parameter 'taskId' documented as '任务ID' (task ID). The description doesn't add meaning beyond the schema, such as format examples or sourcing guidance. Baseline 3 is appropriate since the schema does the heavy lifting, but no extra value is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '取消下载任务' (Cancel download task) clearly states the action (cancel) and target resource (download task). It distinguishes from siblings like 'download_video' (initiates download) and 'get_task_status' (checks status), though it doesn't explicitly differentiate them. The purpose is specific but lacks explicit sibling comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives is provided. The description doesn't mention prerequisites (e.g., task must be active), exclusions (e.g., cannot cancel completed tasks), or relationships with siblings like 'get_task_status' for verification. Usage is implied only by the action name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

download_videoC

下载指定URL的视频到本地路径

ParametersJSON Schema
NameRequiredDescriptionDefault
audioFormatNo音频格式mp3
downloadSubtitlesNo是否下载字幕
extractAudioNo是否仅提取音频
outputPathYes本地保存路径
outputTemplateNo输出文件名模板%(title)s.%(ext)s
qualityNo视频质量选项best
subtitleLangsNo字幕语言列表
urlYes视频链接URL

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the basic action (download video) but doesn't describe what happens during execution: whether it's synchronous/asynchronous, if it creates background tasks, error handling, file system impacts, or performance characteristics. For a tool with 8 parameters and no annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient Chinese sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a download tool and front-loads the core functionality. Every word earns its place with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex video download tool with 8 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns (success/failure indicators, file paths, task IDs), doesn't mention behavioral aspects like async processing (suggested by sibling task tools), and provides minimal context beyond the basic action. The description should do more given the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly with descriptions, defaults, enums, and required status. The description adds no parameter-specific information beyond what's in the schema. Baseline 3 is appropriate when schema does all the parameter documentation work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('下载' meaning download) and target resource ('指定URL的视频'), specifying it downloads video from a URL to a local path. It distinguishes from siblings like get_video_info (info retrieval) and list_tasks (task listing), but doesn't explicitly differentiate from cancel_task or get_task_status which are task management tools. The purpose is clear but sibling differentiation is implicit rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. While it's obvious this is for downloading videos (unlike get_video_info for info retrieval), there's no mention of prerequisites, constraints, or when to choose other tools like cancel_task for task management. Usage context is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_task_statusC

获取下载任务状态

ParametersJSON Schema
NameRequiredDescriptionDefault
taskIdYes任务ID

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('get') but doesn't explain what 'status' entails (e.g., progress percentage, success/failure, error details), response format, or any side effects like rate limits or authentication needs, leaving significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient phrase ('获取下载任务状态') that directly states the purpose without unnecessary words. It's front-loaded and appropriately sized for a simple tool, with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a status-checking operation with no annotations and no output schema), the description is incomplete. It doesn't cover what the status includes, how to interpret results, or error handling, making it inadequate for effective agent use despite the concise phrasing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with 'taskId' documented as '任务ID' (task ID). The description doesn't add meaning beyond this, such as format examples or where to obtain the ID, but the schema provides adequate baseline information, justifying a score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '获取下载任务状态' (Get download task status) clearly states the verb ('get') and resource ('download task status'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'list_tasks' or 'get_video_info', leaving ambiguity about scope and specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description lacks context such as prerequisites (e.g., needing a taskId from another operation) or comparisons to siblings like 'list_tasks' for broader status overviews, leaving usage unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_video_infoB

获取视频信息(不下载)

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes视频链接URL

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool gets video information without downloading, which implies a read-only operation, but doesn't disclose other traits such as rate limits, authentication needs, error handling, or what specific information is returned. This leaves significant gaps for an AI agent to understand the tool's behavior fully.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and front-loaded, consisting of a single, clear phrase: '获取视频信息(不下载)'. Every word earns its place by specifying the action, resource, and a key constraint, with zero waste or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (retrieving video info), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what information is returned (e.g., metadata, duration, format), potential errors, or how it interacts with sibling tools like 'list_tasks'. This leaves the AI agent with insufficient context for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the parameter 'url' clearly documented as '视频链接URL' (video link URL). The description adds no additional meaning beyond this, as it doesn't elaborate on URL formats, supported platforms, or validation rules. Given the high schema coverage, a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('获取' meaning 'get') and resource ('视频信息' meaning 'video information'), and explicitly distinguishes it from downloading ('不下载' meaning 'not download'). However, it doesn't differentiate from sibling tools like 'get_task_status' which might also retrieve information, so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying 'not download', suggesting this tool is for metadata retrieval rather than file acquisition. However, it doesn't explicitly state when to use this versus alternatives like 'download_video' or 'list_tasks', nor does it provide context about prerequisites or exclusions, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tasksB

列出所有下载任务

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. '列出所有下载任务' implies a read-only listing operation, but it doesn't disclose behavioral traits like whether it returns active/completed tasks, pagination, sorting, rate limits, authentication needs, or error conditions. For a listing tool with zero annotation coverage, this leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient phrase ('列出所有下载任务') that directly states the purpose with zero waste. It's appropriately sized for a simple listing tool and front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks details on behavior, output format, or usage context. For a listing tool, it should ideally clarify scope (e.g., all tasks vs. filtered) or return structure, but the absence of an output schema increases the burden slightly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage (empty schema). The description doesn't need to add parameter semantics, so it meets the baseline. No compensation is required, and it doesn't introduce confusion about parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '列出所有下载任务' (List all download tasks) clearly states the verb (list) and resource (download tasks). It distinguishes from siblings like 'cancel_task' (action) and 'get_task_status' (status query) by indicating it returns all tasks rather than specific ones. However, it doesn't explicitly differentiate from 'get_video_info' which might return different resource types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'get_task_status' for specific task details or 'cancel_task' for task management. It doesn't mention prerequisites, context for usage, or any exclusions. The agent must infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.0
    • First observedcancel_task
    • First observeddownload_video
    • First observedget_task_status
    • First observedget_video_info
    • First observedlist_tasks

TDQS

A3.5/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: cancel_task stops tasks, download_video initiates downloads, get_task_status checks progress, get_video_info retrieves metadata, and list_tasks enumerates tasks. An agent can easily distinguish between these operations.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (e.g., cancel_task, download_video, get_task_status), using snake_case throughout. The naming is predictable and readable across the entire set.

Tool Count5/5

With 5 tools, this server is well-scoped for video fetching, covering core operations like downloading, status checking, task management, and info retrieval. Each tool earns its place without being excessive or insufficient.

Completeness4/5

The toolset covers the essential lifecycle of video fetching: initiating downloads (download_video), monitoring (get_task_status, list_tasks), and metadata retrieval (get_video_info). A minor gap is the lack of a tool for modifying or resuming tasks, but agents can work around this with the existing tools.

Related MCP Connectors

Related MCP Servers