Video Clip MCP

🚀 Video Clip MCP

A professional video editing tool based on the AI MCP protocol, offering efficient video processing capabilities and an intelligent operation experience. No need to manually install FFmpeg, it's ready to use out of the box!

🚀 Quick Start

This tool simplifies video processing. Just install it and start editing videos right away.

✨ Features

• 🎯 Precise Editing - Supports video segment cropping with millisecond-level precision.
• 🔗 Intelligent Merging - Seamlessly stitches multiple video files together, automatically adapting to format differences.
• ✂️ Flexible Splitting - Intelligently splits videos by duration, size, or number of segments.
• 📊 Information Retrieval - Conducts detailed video metadata analysis and format detection.
• 🚀 Batch Processing - Efficiently manages batch tasks and performs parallel processing.
• 🎨 Multi-format Support - Supports mainstream video formats and encoding standards.
• 📈 Task Monitoring - Tracks real-time task status and manages progress.
• 🛠️ Highly Configurable - Offers a wide range of encoding parameters and quality presets.

📦 Installation

Global Installation (Recommended)

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

Temporary Use

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

🔧 MCP Server Configuration

Claude Desktop

Add the following to claude_desktop_config.json:

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

Cursor AI

Add the following to .cursorrules or the project configuration:

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

WindSurf

Configure in windsurfconfig.json:

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

CodeBuddy

Create .codebuddy/mcp.json in the project root directory:

{
  "servers": {
    "video-clip": {
      "command": "npx @pickstar-2002/video-clip-mcp@latest",
      "description": "🎬 Video editing and processing tool"
    }
  }
}

Other MCP-compatible Tools

General configuration format:

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

💻 Usage Examples

Basic Usage

// Clip a video segment (from 10 seconds to 30 seconds)
await clipVideo({
  inputPath: "input.mp4",
  outputPath: "output.mp4",
  timeSegment: {
    start: 10000,  // 10 seconds (milliseconds)
    end: 30000     // 30 seconds (milliseconds)
  },
  quality: "fast",
  videoCodec: "libx264"
});

Advanced Usage

Video Merging

// Merge multiple video files
await mergeVideos({
  inputPaths: ["video1.mp4", "video2.mp4", "video3.mp4"],
  outputPath: "merged.mp4",
  quality: "medium",
  resolution: { width: 1920, height: 1080 }
});

Video Splitting

// Split a video by duration
await splitVideo({
  inputPath: "long_video.mp4",
  outputDir: "./segments",
  splitBy: "duration",
  duration: 60,  // Every 60 seconds
  namePattern: "segment_{index}.{ext}"
});

Batch Processing

// Batch processing tasks
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 });

🎥 Supported Formats

Video Formats

• Input Formats: MP4, AVI, MOV, MKV, WebM, FLV, 3GP, WMV
• Output Formats: MP4, AVI, MOV, MKV, WebM

Video Encoding

• H.264 (libx264) - Best for general compatibility.
• H.265 (libx265) - High compression ratio, smaller file size.
• VP9 (libvpx-vp9) - Open-source encoding, suitable for network transmission.
• AV1 (libaom-av1) - Next-generation encoding, extremely high compression efficiency.

Audio Encoding

• AAC - High-quality audio encoding.
• MP3 (libmp3lame) - General compatibility.
• Opus (libopus) - Low latency and high quality.
• Vorbis (libvorbis) - Open-source audio encoding.

🖥️ System Requirements

Node.js Version

• Minimum Requirement: Node.js 18.0.0+
• Recommended Version: Node.js 20.0.0+

System Dependencies

• FFmpeg: Automatically installed (via the @ffmpeg-installer/ffmpeg package).
• Operating System: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+).

Recommended Hardware Configuration

• CPU: 4 or more cores, hardware acceleration is preferred.
• Memory: 8GB RAM or more.
• Storage: SSD hard drive with at least 2GB of available space.
• GPU: Graphics card supporting hardware encoding (optional).

📚 Documentation

Core Interface Definitions

interface VideoClipOptions {
  inputPath: string;
  outputPath: string;
  timeSegment: {
    start: number;  // Start time (milliseconds)
    end: number;    // End time (milliseconds)
  };
  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;     // Split by duration (seconds)
  maxSize?: number;      // Split by size (MB)
  segmentCount?: number; // Number of segments
  namePattern?: string;  // File naming pattern
}

interface VideoInfo {
  duration: number;      // Duration (seconds)
  width: number;         // Width
  height: number;        // Height
  fps: number;          // Frames per second
  bitrate: number;      // Bitrate
  format: string;       // Format
  codec: string;        // Encoding
  size: number;         // File size (bytes)
}

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

Main Methods

// Get video information
getVideoInfo(filePath: string): Promise<VideoInfo>

// Clip a video
clipVideo(options: VideoClipOptions): Promise<string>

// Merge videos
mergeVideos(options: MergeVideosOptions): Promise<string>

// Split a video
splitVideo(options: SplitVideoOptions): Promise<string[]>

// Batch processing
batchProcess(tasks: BatchTask[]): Promise<string[]>

// Get task status
getTaskStatus(taskId: string): Promise<TaskStatus>

// Cancel a task
cancelTask(taskId: string): Promise<boolean>

// Get supported formats
getSupportedFormats(): Promise<SupportedFormats>

🚨 Troubleshooting

Common Issues and Solutions

1. 🔄 Connection closed Error

Problem Description: A connection closed error occurs when using npx. Solutions (in recommended order): a. Preferred Solution - Use the @latest Tag

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

b. Alternative Solution - Lock to a Specific Version

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

c. Ultimate Solution - Clear the npx Cache

# Windows
npx clear-npx-cache
# Or manually delete the cache directory
rmdir /s "%APPDATA%\npm-cache\_npx"

# macOS/Linux
npx clear-npx-cache
# Or manually delete the cache directory
rm -rf ~/.npm/_npx

2. 🎬 FFmpeg-related Errors

Problem Description: FFmpeg fails to execute or cannot be found. Solutions:

• This tool has FFmpeg built-in, so there's no need to install it manually.
• If the problem persists, check your network connection (FFmpeg needs to be downloaded on first use).
• Ensure there is enough disk space (at least 100MB).

3. 📁 File Path Issues

Problem Description: Incorrect input or output file paths. Solutions:

• Use absolute paths instead of relative paths.
• Ensure there are no special characters in the path.
• Windows users should use forward slashes / or double backslashes \\.

4. 🔧 Permission Issues

Problem Description: Lack of file read/write permissions. Solutions:

• Ensure you have read permissions for the input file.
• Ensure you have write permissions for the output directory.
• Windows users may need to run as an administrator.

5. 💾 Insufficient Memory

Problem Description: Memory overflow when processing large files. Solutions:

• Reduce the video quality settings.
• Process large files in segments.
• Increase the system's virtual memory.

📞 Getting Help

If the above solutions do not solve your problem, please:

1. 📋 Collect error information and system environment details.
2. 🐛 Submit an issue on GitHub Issues.
3. 💬 Contact the developer (see contact information below).

🤝 Contribution Guidelines

We welcome all forms of contribution! 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 amazing feature'.
4. Push the branch: git push origin feature/amazing-feature.
5. Submit a Pull Request.

Development Environment Setup

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

# Install dependencies
npm install

# Build the project
npm run build

# Start development mode
npm run dev

📄 License

This project is licensed under the MIT License. You are free to use, modify, and distribute this software.

🙏 Acknowledgments

Thanks to the support of the following open-source projects and communities:

• FFmpeg - A powerful multimedia processing framework.
• fluent-ffmpeg - A Node.js FFmpeg wrapper library.
• Model Context Protocol - An AI tool integration protocol.
• TypeScript - A type-safe superset of JavaScript.
• The open-source community - Support from all contributors and users.

🌟 Support the Project

If this project is helpful to you, please:

• ⭐ Star the project
• 🐛 Report issues and suggestions
• 🔄 Share it with more developers

Let's build a better video processing tool together! 🚀

📞 Contact Information

WeChat: pickstar_loveXX