🎬 Video Convert MCP

NPM Version License Node.js Downloads

一款基于 MCP (Model Context Protocol) 协议的强大、高效的视频格式转换工具。支持在 AI 编程助手中直接进行视频格式转换，让视频处理变得前所未有的简单。

✨ 功能特性

🚀 多格式转换: 支持 MP4、AVI、MOV、WMV、MKV、WEBM、M4V 等主流视频格式之间的相互转换
⚡ 批量处理: 一次性处理多个视频文件，大幅提升工作效率
📊 质量控制: 提供 low、medium、high、ultra 四档质量预设，完美平衡文件大小和画质
🔧 详细信息: 轻松获取视频的详细元数据，如格式、分辨率、时长、码率等
🔒 类型安全: 使用 TypeScript 开发，提供完整的类型定义，确保调用安全
📦 零配置: 内置 FFmpeg，用户无需在本地安装任何额外依赖，开箱即用

🛠️ 安装与配置

本工具是一个 MCP 服务，无需全局安装。您只需在支持 MCP 的 AI 编程助手（如 CodeBuddy、Cursor、Claude Desktop 等）中进行配置即可使用。

CodeBuddy 配置

打开 CodeBuddy 的 MCP 配置文件 codebuddy_mcp_settings.json，在 mcpServers 对象中添加以下配置：

{
  "mcpServers": {
    "video-convert": {
      "timeout": 60,
      "type": "stdio",
      "command": "npx",
      "args": [
        "@pickstar-2002/video-convert-mcp@latest"
      ]
    }
  }
}

Cursor 配置

在 Cursor 的设置中找到 MCP 配置，添加：

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

Claude Desktop 配置

编辑 claude_desktop_config.json 文件：

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

💡 推荐使用 @latest 标签来确保您总能使用最新的稳定版本。

🚨 疑难解答 (Troubleshooting)

常见问题 1: Connection closed 错误

问题: 遇到 MCP error -32000: Connection closed 或类似的连接错误。

原因: 这通常是 npx 的缓存问题导致的。如果您之前运行过旧版本的包，npx 可能会继续使用缓存中的旧版本。

解决方案 (按推荐顺序)：

首选方案: 确认使用了 @latest 标签

"args": ["@pickstar-2002/video-convert-mcp@latest"]

备用方案: 锁定到特定的稳定版本号

"args": ["@pickstar-2002/video-convert-mcp@1.2.1"]

终极方案: 清理 npx 缓存

# Windows
npm config get cache
# 然后删除缓存目录中的 _npx 文件夹

# macOS/Linux
rm -rf ~/.npm/_npx

常见问题 2: FFmpeg 相关错误

问题: 提示找不到 FFmpeg 或 FFmpeg 执行失败。

解决方案: 本工具内置了 FFmpeg，通常不会出现此问题。如果遇到，请尝试：

重启您的 AI 编程助手
检查网络连接（首次运行时需要下载依赖）

常见问题 3: 权限错误

问题: 在某些系统上可能遇到权限相关的错误。

解决方案:

确保输出目录有写入权限
在 Windows 上，尝试以管理员身份运行您的 AI 编程助手

📖 API 文档

本 MCP 服务提供了以下工具：

`convert_video`

转换单个视频文件为指定格式。

参数:

inputPath (string, 必填): 输入视频文件的完整路径
outputFormat (string, 必填): 目标输出格式，支持: mp4, avi, mov, wmv, mkv, webm, m4v
outputPath (string, 可选): 输出文件路径，不指定则自动生成
quality (string, 可选): 视频质量预设 (low, medium, high, ultra)
resolution (string, 可选): 输出分辨率，格式为 "宽度x高度"，如 "1920x1080"
videoBitrate (number, 可选): 视频码率，单位 kbps
audioBitrate (number, 可选): 音频码率，单位 kbps
frameRate (number, 可选): 输出帧率，单位 fps
overwrite (boolean, 可选): 是否覆盖已存在的输出文件，默认 false

示例:

// 基本转换
convert_video({
  inputPath: "/path/to/input.avi",
  outputFormat: "mp4"
})

// 高质量转换
convert_video({
  inputPath: "/path/to/input.mov",
  outputFormat: "mp4",
  quality: "high",
  resolution: "1920x1080"
})

`batch_convert`

批量转换多个视频文件。

参数:

inputFiles (string[], 必填): 输入视频文件路径数组
outputFormat (string, 必填): 目标输出格式
outputDir (string, 必填): 输出目录路径
quality (string, 可选): 视频质量预设
overwrite (boolean, 可选): 是否覆盖已存在的输出文件

示例:

batch_convert({
  inputFiles: [
    "/path/to/video1.avi",
    "/path/to/video2.mov",
    "/path/to/video3.wmv"
  ],
  outputFormat: "mp4",
  outputDir: "/path/to/output",
  quality: "high"
})

`get_video_info`

获取视频文件的详细信息。

参数:

filePath (string, 必填): 视频文件的完整路径

返回信息:

文件格式和编解码器信息
视频分辨率、帧率、码率
音频采样率、声道数、码率
文件大小和时长
元数据信息

示例:

get_video_info({
  filePath: "/path/to/video.mp4"
})

🎯 使用示例

基本转换

请帮我将 /Users/john/Desktop/video.avi 转换为 MP4 格式

批量转换

请将 /Users/john/Videos/ 目录下的所有 AVI 文件批量转换为 MP4 格式，输出到 /Users/john/Converted/ 目录

获取视频信息

请帮我查看 /Users/john/movie.mp4 的详细信息

高质量转换

请将 /Users/john/raw_video.mov 转换为高质量的 MP4 格式，分辨率设置为 1920x1080

🤝 贡献指南

欢迎各种形式的贡献！如果您有任何想法、建议或发现了 bug，请随时参与到项目中来。

如何贡献

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

开发环境设置

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

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建项目
npm run build

📄 许可证

本项目使用 MIT 许可证。详情请查看 LICENSE 文件。

🔗 相关链接

📧 联系作者

如果您有任何问题、建议或合作意向，欢迎联系我！

微信: pickstar_loveXX

⭐ 如果这个项目对您有帮助，请给个 Star 支持一下！⭐

Made with ❤️ by pickstar-2002