Video & Audio Editing MCP Server

🎬 视频和音频编辑MCP服务器

一个全面的模型上下文协议（MCP）服务器，通过FFmpeg提供强大的视频和音频编辑功能。该服务器使AI助手能够执行专业级的视频编辑操作，包括格式转换、修剪、叠加、过渡和高级音频处理。

✨ 特性

• 🎥 视频处理：格式转换、分辨率缩放、编解码器更改、帧率调整
• 🎵 音频处理：格式转换、比特率调整、采样率更改、信道配置
• ✂️ 编辑工具：视频剪辑、速度调整、宽高比更改
• 🎨 叠加和效果：文本叠加、图像水印、字幕刻录
• 🔗 高级编辑：带过渡的视频拼接、插入B-roll、消除静音
• 🎭 过渡：淡入/淡出效果，剪辑之间的渐变过渡

🛠️ 可用工具

核心视频操作

• extract_audio_from_video -从视频文件中提取音轨
• trim_video -精确定时剪切视频片段
• convert_video_format -在视频格式（MP4、MOV、AVI等）之间转换
• convert_video_properties -全面的视频属性转换
• change_aspect_ratio -通过填充或裁剪调整视频宽高比
• set_video_resolution -更改视频分辨率以保持质量
• set_video_codec -切换视频编解码器（H.264、H.265、VP9等）
• set_video_bitrate -调整视频质量和文件大小
• set_video_frame_rate -更改播放帧率

音频处理

• convert_audio_format -在音频格式（MP3、WAV、AAC等）之间转换
• convert_audio_properties -全面的音频属性转换
• set_audio_bitrate -调整音频质量和压缩
• set_audio_sample_rate -更改音频采样率
• set_audio_channels -在单声道和立体声之间转换
• set_video_audio_track_codec -更改视频文件中的音频编解码器
• set_video_audio_track_bitrate -调整视频中的音频比特率
• set_video_audio_track_sample_rate -更改视频中的音频采样率
• set_video_audio_track_channels -调整视频中的音频通道

创造性工具

• add_subtitles -使用自定义样式刻录字幕
• add_text_overlay -添加带有计时功能的动态文本叠加
• add_image_overlay -插入水印和徽标
• add_b_roll -插入带有过渡的B-roll镜头
• add_basic_transitions -应用淡入/淡出效果

高级编辑

• concatenate_videos -使用可选过渡连接多个视频
• change_video_speed -创建慢动作或延时效果
• remove_silence -自动删除无声片段
• health_check -验证服务器状态

🚀 快速开始

先决条件（本地安装）

1. Python 3.8+ - 下载Python
2. FFmpeg - 安装FFmpeg
3. 紫外线 （推荐）- 安装uv 或使用pip

安装

选项1：使用Smithery（最简单）⭐

最简单的开始方式是通过 Smithery MCP注册处:

选项2：使用紫外线（建议用于开发）

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/misbahsy/video-audio-mcp.git
cd video-audio-mcp

# Install dependencies with uv
uv sync

# Verify FFmpeg installation
ffmpeg -version

运行服务器

# With uv (recommended)
uv run server.py

# Or with traditional python
python server.py

# Or with specific transport
python -c "from server import mcp; mcp.run(transport='stdio')"

🔧 客户端配置

Claude桌面（推荐配置）

添加到您的 claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "VideoAudioServer": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/video-audio-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

替代方案（直接使用Python）：

{
  "mcpServers": {
    "VideoAudioServer": {
      "command": "python",
      "args": ["/path/to/video-audio-mcp/server.py"]
    }
  }
}

游标IDE（推荐配置）

1. 打开光标设置： File → Preferences → Cursor Settings → MCP
2. 点击“添加新服务器”
3. 配置：

- 名字: VideoAudioServer - 类型: command - 命令: uv --directory /path/to/your/video-audio-mcp run server.py

替代配置：

• 命令: /path/to/python /path/to/video-audio-mcp/server.py

帆板运动

添加到MCP配置中：

{
  "mcpServers": {
    "VideoAudioServer": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/video-audio-mcp",
        "run",
        "server.py"
      ],
      "env": {}
    }
  }
}

为什么要使用紫外线？

这 uv 建议使用命令，因为它：

• 自动管理依赖关系 无需激活虚拟环境
• 安装速度更快 和依赖关系解决
• 更好的隔离 -每个项目都会自动获得自己的环境
• 更可靠 -更好地处理Python版本和依赖冲突
• 现代模具 -Python包管理的未来

使用NPX（替代方案）

为了更容易分发，如果打包，您还可以通过npx运行：

{
  "mcpServers": {
    "VideoAudioServer": {
      "command": "npx",
      "args": ["-y", "video-audio-mcp-server"]
    }
  }
}

📖 使用示例

基本视频编辑

"Can you convert this MP4 file to MOV format?"
→ Uses: convert_video_format

"Trim the video from 30 seconds to 2 minutes"
→ Uses: trim_video

"Extract the audio from this video as MP3"
→ Uses: extract_audio_from_video

高级编辑工作流

"Create a highlight reel by concatenating these 3 clips with fade transitions"
→ Uses: concatenate_videos with transition effects

"Add my logo watermark to the top-right corner of this video"
→ Uses: add_image_overlay

"Remove all silent parts from this podcast recording"
→ Uses: remove_silence

"Add subtitles to this video with custom styling"
→ Uses: add_subtitles

专业工作流程

"Convert this 4K video to 1080p, reduce bitrate to 2Mbps, and change to H.265 codec"
→ Uses: convert_video_properties

"Create a social media version: change to 9:16 aspect ratio, add text overlay, and compress"
→ Uses: change_aspect_ratio, add_text_overlay, set_video_bitrate

"Insert B-roll footage at 30 seconds with a fade transition"
→ Uses: add_b_roll

🎯 真实世界用例

内容创作

• YouTube视频：自动编辑、缩略图生成、格式优化
• 社交媒体：宽高比转换、文本叠加、平台压缩
• 播客：音频提取、静音消除、格式转换

专业视频制作

• 企业视频：徽标水印、字幕添加、质量标准化
• 教育内容：屏幕录制处理、章节标记、辅助功能
• 市场营销材料：B-roll整合、过渡效果、品牌一致性

工作流程自动化

• 批处理：将整个视频库转换为新格式
• 质量控制：跨项目标准化视频属性
• 档案管理：提取音频进行转录，创建预览剪辑

🔍 工具参考

格式转换

# Convert MP4 to MOV with specific properties
convert_video_properties(
    input_video_path="input.mp4",
    output_video_path="output.mov",
    target_format="mov",
    resolution="1920x1080",
    video_codec="libx264",
    video_bitrate="5M",
    frame_rate=30
)

带时间的文本叠加

# Add multiple text overlays with different timings
add_text_overlay(
    video_path="input.mp4",
    output_video_path="output.mp4",
    text_elements=[
        {
            "text": "Welcome to our presentation",
            "start_time": "0",
            "end_time": "3",
            "font_size": 48,
            "font_color": "white",
            "x_pos": "center",
            "y_pos": "center"
        },
        {
            "text": "Chapter 1: Introduction",
            "start_time": "5",
            "end_time": "8",
            "font_size": 36,
            "box": True,
            "box_color": "black@0.7"
        }
    ]
)

高级连接

# Join videos with crossfade transition
concatenate_videos(
    video_paths=["clip1.mp4", "clip2.mp4"],
    output_video_path="final.mp4",
    transition_effect="dissolve",
    transition_duration=1.5
)

🛡️ 错误处理

服务器包括全面的错误处理：

• 文件验证：处理前检查文件是否存在
• 格式支持：验证支持的格式和编解码器
• 优雅的退路：在重新编码之前尝试编解码器复制
• 详细日志：为故障排除提供清晰的错误消息

🔧 故障排除

常见问题

未找到FFmpeg

# Install FFmpeg
# macOS: brew install ffmpeg
# Ubuntu: sudo apt install ffmpeg
# Windows: Download from https://ffmpeg.org/

权限错误

# Ensure file permissions
chmod +x server.py

MCP服务器未连接

1. 检查配置中的文件路径
2. 验证Python环境
3. 手动测试服务器： python server.py
4. 检查客户端日志以了解详细错误

调试模式

运行调试日志：

python server.py --log-level DEBUG

🧪 测试

该项目包括一个全面的测试套件，用于验证所有视频和音频编辑功能。这些测试确保了可靠性，并有助于在开发过程中发现回归。

测试覆盖率

测试套件包括：

• ✅ 核心功能：所有30+视频/音频编辑工具
• 🎬 视频操作：格式转换、修剪、分辨率更改、编解码器切换
• 🎵 音频处理：比特率调整、采样率更改、信道配置
• 🎨 创造性工具：文本叠加、图像水印、字幕刻录
• 🔗 高级功能：视频拼接、B-roll插入、过渡
• ⚡ 演出：速度变化、静音消除、宽高比调整
• 🛡️ 错误处理：输入无效、文件丢失、格式不受支持

运行测试

测试的先决条件

# Install test dependencies
pip install pytest

# Ensure FFmpeg is installed and accessible
ffmpeg -version

基本测试执行

# Run all tests
pytest tests/

# Run with verbose output
pytest tests/ -v

# Run specific test file
pytest tests/test_video_functions.py

# Run specific test function
pytest tests/test_video_functions.py::test_extract_audio

高级测试选项

# Run tests with detailed output and no capture
pytest tests/ -v -s

# Run tests and stop on first failure
pytest tests/ -x

# Run tests with coverage report
pytest tests/ --cov=server

# Run only failed tests from last run
pytest tests/ --lf

测试环境设置

测试套件会自动创建：

• 示例文件：测试视频、音频文件和图像
• 输出目录: tests/test_outputs/ 对于生成的文件
• 临时文件：B辊夹和过渡试验材料

# Test files are created in:
tests/
├── test_outputs/          # Generated test results
├── sample_files/          # Auto-generated sample media
├── test_video_functions.py # Main test suite
└── sample.mp4            # Primary test video (if available)

样本测试输出

$ pytest tests/test_video_functions.py -v

tests/test_video_functions.py::test_health_check PASSED
tests/test_video_functions.py::test_extract_audio PASSED
tests/test_video_functions.py::test_trim_video PASSED
tests/test_video_functions.py::test_convert_audio_properties PASSED
tests/test_video_functions.py::test_convert_video_properties PASSED
tests/test_video_functions.py::test_add_text_overlay PASSED
tests/test_video_functions.py::test_add_subtitles PASSED
tests/test_video_functions.py::test_concatenate_videos PASSED
tests/test_video_functions.py::test_add_b_roll PASSED
tests/test_video_functions.py::test_add_basic_transitions PASSED
tests/test_video_functions.py::test_concatenate_videos_with_xfade PASSED

========================= 25 passed in 45.2s =========================

测试类别

🎯 核心功能测试

• 视频格式转换和属性更改
• 音频提取和处理
• 文件修剪和基本操作

🎨 创意功能测试

• 文本叠加定位和定时
• 图像水印的放置和不透明度
• 字幕燃烧与自定义样式

🔗 高级编辑测试

• 带过渡的多视频拼接
• B辊插入，具有多种位置
• 速度变化和静音消除

🛡️ 错误处理测试

• 无效的文件路径和丢失的文件
• 不支持的格式和编解码器
• 边缘情况和边界条件

编写自定义测试

要为附加功能添加新测试，请执行以下操作：

def test_new_feature():
    """Test description"""
    # Setup
    input_file = "path/to/test/file.mp4"
    output_file = os.path.join(OUTPUT_DIR, "test_output.mp4")
    
    # Execute
    result = your_new_function(input_file, output_file, parameters)
    
    # Validate
    assert "success" in result.lower()
    assert os.path.exists(output_file)
    
    # Optional: Validate output properties
    duration = get_media_duration(output_file)
    assert duration > 0

持续集成

该测试套件设计用于CI/CD环境：

# Example GitHub Actions workflow
- name: Install FFmpeg
  run: sudo apt-get install ffmpeg

- name: Install dependencies
  run: pip install -r requirements.txt pytest

- name: Run tests
  run: pytest tests/ -v

性能测试

一些测试包括性能验证：

• 持续时间检查：验证输出视频长度是否符合预期
• 质量验证：确保格式转换保持质量
• 文件大小监控：检查压缩和比特率变化

测试数据管理

• 自动清理：测试清理临时文件
• 样本生成：根据需要创建测试媒体文件
• 确定性结果：测试产生一致、可重复的结果

💡 小贴士：在任何更改后运行测试，以确保功能保持不变。全面的测试套件在大多数问题进入生产之前就捕捉到了它们。

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发设置

# Clone and setup development environment
git clone https://github.com/misbahsy/video-audio-mcp.git
cd video-audio-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 内置于 FastMCP 框架
• 由...驱动 FFmpeg 用于媒体处理
• 灵感来自 模型上下文协议 规格

📞 支持

• 🐛 错误报告:

______________________________________________________________________

由...制作❤️ 对于MCP社区