README.md•7.78 kB
# 🎬 Video Convert MCP
[](https://www.npmjs.com/package/@pickstar-2002/video-convert-mcp)
[](https://github.com/pickstar-2002/video-convert-mcp/blob/main/LICENSE)
[](https://nodejs.org/)
[](https://www.npmjs.com/package/@pickstar-2002/video-convert-mcp)
一款基于 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` 对象中添加以下配置：
```json
{
"mcpServers": {
"video-convert": {
"timeout": 60,
"type": "stdio",
"command": "npx",
"args": [
"@pickstar-2002/video-convert-mcp@latest"
]
}
}
}
```
### Cursor 配置
在 Cursor 的设置中找到 MCP 配置，添加：
```json
{
"mcpServers": {
"video-convert": {
"command": "npx",
"args": ["@pickstar-2002/video-convert-mcp@latest"]
}
}
}
```
### Claude Desktop 配置
编辑 `claude_desktop_config.json` 文件：
```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` 可能会继续使用缓存中的旧版本。
**解决方案** (按推荐顺序)：
1. **首选方案**: 确认使用了 `@latest` 标签
```json
"args": ["@pickstar-2002/video-convert-mcp@latest"]
```
2. **备用方案**: 锁定到特定的稳定版本号
```json
"args": ["@pickstar-2002/video-convert-mcp@1.2.1"]
```
3. **终极方案**: 清理 `npx` 缓存
```bash
# 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
**示例**:
```typescript
// 基本转换
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, 可选): 是否覆盖已存在的输出文件
**示例**:
```typescript
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, 必填): 视频文件的完整路径
**返回信息**:
- 文件格式和编解码器信息
- 视频分辨率、帧率、码率
- 音频采样率、声道数、码率
- 文件大小和时长
- 元数据信息
**示例**:
```typescript
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，请随时参与到项目中来。
### 如何贡献
1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request
### 开发环境设置
```bash
# 克隆仓库
git clone https://github.com/pickstar-2002/video-convert-mcp.git
cd video-convert-mcp
# 安装依赖
npm install
# 开发模式运行
npm run dev
# 构建项目
npm run build
```
## 📄 许可证
本项目使用 [MIT](https://opensource.org/licenses/MIT) 许可证。详情请查看 [LICENSE](LICENSE) 文件。
## 🔗 相关链接
- [NPM 包地址](https://www.npmjs.com/package/@pickstar-2002/video-convert-mcp)
- [GitHub 仓库](https://github.com/pickstar-2002/video-convert-mcp)
- [问题反馈](https://github.com/pickstar-2002/video-convert-mcp/issues)
- [MCP 协议文档](https://modelcontextprotocol.io/)
## 📧 联系作者
如果您有任何问题、建议或合作意向，欢迎联系我！
**微信**: pickstar_loveXX
---
<div align="center">
**⭐ 如果这个项目对您有帮助，请给个 Star 支持一下！⭐**
Made with ❤️ by [pickstar-2002](https://github.com/pickstar-2002)
</div>