Video Clip MCP

🚀 🎬 Video Clip MCP

基於 AI MCP 協議的專業視頻剪輯工具，提供高效的視頻處理能力和智能化操作體驗。無需手動安裝 FFmpeg，開箱即用！

🚀 快速開始

本工具是基於 AI MCP 協議的專業視頻剪輯工具，具備高效的視頻處理能力和智能化操作體驗，且無需手動安裝 FFmpeg。

安裝

全局安裝（推薦）

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

臨時使用

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

MCP 服務器配置

Claude Desktop

在 claude_desktop_config.json 中添加：

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

Cursor AI

在 .cursorrules 或項目配置中添加：

{
  "mcp": {
    "servers": {
      "video-clip": {
        "command": "npx @pickstar-2002/video-clip-mcp@latest"
      }
    }
  }
}

WindSurf

在 windsurfconfig.json 中配置：

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

CodeBuddy

在項目根目錄創建 .codebuddy/mcp.json：

{
  "servers": {
    "video-clip": {
      "command": "npx @pickstar-2002/video-clip-mcp@latest",
      "description": "🎬 視頻剪輯處理工具"
    }
  }
}

其他 MCP 兼容工具

通用配置格式：

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

✨ 主要特性

• 🎯 精準剪輯 - 支持毫秒級精度的視頻片段裁剪
• 🔗 智能合併 - 多視頻文件無縫拼接，自動適配格式差異
• ✂️ 靈活分割 - 按時長、大小或段數智能分割視頻
• 📊 信息獲取 - 詳細的視頻元數據分析和格式檢測
• 🚀 批量處理 - 高效的批量任務管理和並行處理
• 🎨 多格式支持 - 支持主流視頻格式和編碼標準
• 📈 任務監控 - 即時任務狀態跟蹤和進度管理
• 🛠️ 高度可配置 - 豐富的編碼參數和質量預設

📦 安裝指南

全局安裝（推薦）

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

臨時使用

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

💻 使用示例

基礎用法

基礎視頻剪輯

// 剪輯視頻片段（10秒到30秒）
await clipVideo({
  inputPath: "input.mp4",
  outputPath: "output.mp4",
  timeSegment: {
    start: 10000,  // 10秒（毫秒）
    end: 30000     // 30秒（毫秒）
  },
  quality: "fast",
  videoCodec: "libx264"
});

視頻合併

// 合併多個視頻文件
await mergeVideos({
  inputPaths: ["video1.mp4", "video2.mp4", "video3.mp4"],
  outputPath: "merged.mp4",
  quality: "medium",
  resolution: { width: 1920, height: 1080 }
});

視頻分割

// 按時長分割視頻
await splitVideo({
  inputPath: "long_video.mp4",
  outputDir: "./segments",
  splitBy: "duration",
  duration: 60,  // 每60秒一段
  namePattern: "segment_{index}.{ext}"
});

批量處理

// 批量處理任務
const tasks = [
  {
    type: "clip",
    options: {
      inputPath: "video1.mp4",
      outputPath: "clip1.mp4",
      timeSegment: { start: 0, end: 30000 }
    }
  },
  {
    type: "clip", 
    options: {
      inputPath: "video2.mp4",
      outputPath: "clip2.mp4",
      timeSegment: { start: 10000, end: 40000 }
    }
  }
];

await batchProcess({ tasks });

📚 詳細文檔

支持格式

視頻格式

• 輸入格式: MP4, AVI, MOV, MKV, WebM, FLV, 3GP, WMV
• 輸出格式: MP4, AVI, MOV, MKV, WebM

視頻編碼

• H.264 (libx264) - 通用兼容性最佳
• H.265 (libx265) - 高壓縮比，文件更小
• VP9 (libvpx-vp9) - 開源編碼，適合網絡傳輸
• AV1 (libaom-av1) - 新一代編碼，壓縮效率極高

音頻編碼

• AAC - 高質量音頻編碼
• MP3 (libmp3lame) - 通用兼容性
• Opus (libopus) - 低延遲高質量
• Vorbis (libvorbis) - 開源音頻編碼

系統要求

Node.js 版本

• 最低要求: Node.js 18.0.0+
• 推薦版本: Node.js 20.0.0+

系統依賴

• FFmpeg: 自動安裝（通過 @ffmpeg-installer/ffmpeg 包）
• 操作系統: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+)

推薦硬件配置

• CPU: 4核心以上，支持硬件加速更佳
• 內存: 8GB RAM 以上
• 存儲: SSD 硬盤，至少2GB可用空間
• GPU: 支持硬件編碼的顯卡（可選）

API 文檔

核心接口定義

interface VideoClipOptions {
  inputPath: string;
  outputPath: string;
  timeSegment: {
    start: number;  // 開始時間（毫秒）
    end: number;    // 結束時間（毫秒）
  };
  quality?: 'ultrafast' | 'fast' | 'medium' | 'slow' | 'veryslow';
  videoCodec?: 'libx264' | 'libx265' | 'libvpx-vp9' | 'libaom-av1';
  audioCodec?: 'aac' | 'libmp3lame' | 'libopus' | 'libvorbis';
  preserveMetadata?: boolean;
}

interface MergeVideosOptions {
  inputPaths: string[];
  outputPath: string;
  quality?: string;
  videoCodec?: string;
  audioCodec?: string;
  resolution?: { width: number; height: number };
  fps?: number;
}

interface SplitVideoOptions {
  inputPath: string;
  outputDir: string;
  splitBy: 'duration' | 'size' | 'segments';
  duration?: number;     // 按時長分割（秒）
  maxSize?: number;      // 按大小分割（MB）
  segmentCount?: number; // 分割段數
  namePattern?: string;  // 文件命名模式
}

interface VideoInfo {
  duration: number;      // 時長（秒）
  width: number;         // 寬度
  height: number;        // 高度
  fps: number;          // 幀率
  bitrate: number;      // 比特率
  format: string;       // 格式
  codec: string;        // 編碼
  size: number;         // 文件大小（字節）
}

interface TaskStatus {
  id: string;
  type: 'clip' | 'merge' | 'split';
  status: 'pending' | 'processing' | 'completed' | 'failed';
  progress?: number;
  createdAt: string;
  completedAt?: string;
  error?: string;
  result?: any;
}

主要方法

// 獲取視頻信息
getVideoInfo(filePath: string): Promise<VideoInfo>

// 剪輯視頻
clipVideo(options: VideoClipOptions): Promise<string>

// 合併視頻
mergeVideos(options: MergeVideosOptions): Promise<string>

// 分割視頻
splitVideo(options: SplitVideoOptions): Promise<string[]>

// 批量處理
batchProcess(tasks: BatchTask[]): Promise<string[]>

// 獲取任務狀態
getTaskStatus(taskId: string): Promise<TaskStatus>

// 取消任務
cancelTask(taskId: string): Promise<boolean>

// 獲取支持的格式
getSupportedFormats(): Promise<SupportedFormats>

疑難解答

常見問題及解決方案

1. 🔄 Connection closed 錯誤

問題描述: 使用 npx 時出現連接關閉錯誤

解決方案（按推薦順序）:

• a. 首選方案 - 使用 @latest 標籤

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

• b. 備用方案 - 鎖定特定版本

npx @pickstar-2002/video-clip-mcp@1.2.0

• c. 終極方案 - 清理 npx 緩存

# Windows
npx clear-npx-cache
# 或者手動刪除緩存目錄
rmdir /s "%APPDATA%\npm-cache\_npx"

# macOS/Linux
npx clear-npx-cache
# 或者手動刪除緩存目錄
rm -rf ~/.npm/_npx

2. 🎬 FFmpeg 相關錯誤

問題描述: FFmpeg 執行失敗或找不到

解決方案:

• 本工具已內置 FFmpeg，無需手動安裝
• 如果仍有問題，請檢查網絡連接（首次使用需下載 FFmpeg）
• 確保有足夠的磁盤空間（至少 100MB）

3. 📁 文件路徑問題

問題描述: 輸入或輸出文件路徑錯誤

解決方案:

• 使用絕對路徑而非相對路徑
• 確保路徑中不包含特殊字符
• Windows 用戶注意使用正斜槓 / 或雙反斜槓 \\

4. 🔧 權限問題

問題描述: 沒有文件讀寫權限

解決方案:

• 確保對輸入文件有讀取權限
• 確保對輸出目錄有寫入權限
• Windows 用戶可能需要以管理員身份運行

5. 💾 內存不足

問題描述: 處理大文件時內存溢出

解決方案:

• 降低視頻質量設置
• 分段處理大文件
• 增加系統虛擬內存

獲取幫助

如果以上解決方案無法解決您的問題，請：

1. 📋 收集錯誤信息和系統環境
2. 🐛 在 GitHub Issues 提交問題
3. 💬 聯繫開發者（見下方聯繫方式）

🔧 技術細節

本項目使用了多種開源技術和框架，基於 AI MCP 協議開發。其中，藉助 FFmpeg 進行強大的多媒體處理，通過 fluent-ffmpeg 這個 Node.js FFmpeg 封裝庫簡化操作。使用 TypeScript 保證代碼的類型安全，同時遵循 Model Context Protocol 實現 AI 工具的集成。

📄 許可證

本項目採用 MIT License 開源協議。您可以自由使用、修改和分發本軟件。

🤝 貢獻指南

我們歡迎所有形式的貢獻！請遵循以下步驟：

1. Fork 本倉庫
2. 創建特性分支: git checkout -b feature/amazing-feature
3. 提交更改: git commit -m 'Add amazing feature'
4. 推送分支: git push origin feature/amazing-feature
5. 提交 Pull Request

開發環境設置

# 克隆倉庫
git clone https://github.com/pickstar-2002/video-clip-mcp.git
cd video-clip-mcp

# 安裝依賴
npm install

# 構建項目
npm run build

# 啟動開發模式
npm run dev

🙏 致謝

感謝以下開源項目和社區的支持：

• FFmpeg - 強大的多媒體處理框架
• fluent-ffmpeg - Node.js FFmpeg 封裝庫
• Model Context Protocol - AI 工具集成協議
• TypeScript - 類型安全的 JavaScript 超集
• 開源社區 - 所有貢獻者和用戶的支持

🌟 支持項目

如果這個項目對您有幫助，請：

• ⭐ 給項目點個 Star
• 🐛 報告問題和建議
• 🔄 分享給更多開發者

讓我們一起打造更好的視頻處理工具！🚀

📞 聯繫方式

微信: pickstar_loveXX