Video Gen Mcp

Video Agent MCP 服务

一个用于 AI 驱动视频创作的综合 Model Context Protocol（MCP）服务。该服务提供工具、资源和提示词，指导 AI Agent 完成完整的视频制作工作流。

功能特性

• 统一接口：单个 MCP 服务具备所有视频创作能力
• 多服务集成：支持 FAL AI 服务，用于图像、视频、音频和语音生成
• 智能工作流：可根据项目上下文调整的引导式提示词
• 平台优化：为 YouTube、TikTok、Instagram 等平台预配置设置
• 成本跟踪：实时估算和跟踪所有操作的成本
• YouTube 集成：通过 OAuth2 身份验证直接上传到 YouTube
• 模块化架构：清晰分离工具、资源和提示词

快速开始

前置条件

• Python 3.11+
• 系统中已安装 FFmpeg
• FAL AI API 密钥
• uv（Python 包管理器）

使用 uv 安装

1. 克隆仓库：

git clone <repository-url>
cd video-gen-mcp-monolithic

2. 安装 uv（如果尚未安装）：

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 使用 uv 设置项目：

# uv will automatically:
# - Detect Python 3.11 from .python-version
# - Create a virtual environment
# - Install all dependencies from pyproject.toml
uv sync

# Or if you want to install from requirements.txt:
uv pip install -r requirements.txt

4. 设置环境变量：

# Create a .env file in the project root
cat > .env << EOF
FALAI_API_KEY=your-fal-api-key
# Optional: For YouTube search features
GOOGLE_API_KEY=your-google-api-key
EOF

运行服务

# Run directly with uv (recommended)
uv run python main.py

# Or activate venv and run
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python main.py

配置 Claude Desktop

将以下内容添加到 Claude Desktop 配置中：

macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json Windows 上：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "video-agent": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/video-gen-mcp-monolithic",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "FALAI_API_KEY": "your-fal-api-key"
      }
    }
  }
}

重要：将 /absolute/path/to/video-gen-mcp-monolithic 替换为项目目录的实际路径。

备选方式：使用 pyproject.toml 脚本

由于我们在 pyproject.toml 中定义了脚本入口点，因此也可以运行：

# Install the package in development mode
uv pip install -e .

# Run using the script entry point
uv run video-agent-mcp

使用示例

在 Claude Desktop 中完成配置后，即可开始创建视频：

User: Create a 30-second TikTok video about climate change

Claude: I'll help you create a TikTok video about climate change. Let me start by 
creating a project and planning the scenes...

[Claude uses the video_creation_wizard prompt and various tools to create the video]

可用工具

项目管理

• create_project - 根据平台的智能默认设置初始化新视频项目
• add_scene - 将场景及其描述和时长添加到时间线
• list_projects - 查看所有项目及其当前状态

内容生成

• generate_image_from_text - 使用文本提示词和风格修饰词创建图像
• generate_image_from_image - 使用 AI 编辑功能转换现有图像
• generate_video_from_image - 为静态图像添加 AI 生成的动态效果（支持 Kling 2.1 和 Hailuo 02 模型）
• generate_music - 根据文本描述创作背景音乐
• generate_speech - 使用多种音色选项生成旁白

生成工具

按顺序调用生成工具，以便清晰跟踪进度并更轻松地调试。

视频合成

• download_assets - 从 FAL 或其他来源下载生成的素材
• add_audio_track - 为视频添加音轨并控制音量
• assemble_video - 使用质量预设将多个场景合成为最终视频

实用工具

• analyze_script - 分析脚本，获取视频制作相关见解
• suggest_scenes - 根据项目脚本生成场景建议
• upload_image_file - 将本地图像文件上传到 FAL，以供生成工具使用
• get_server_info - 获取有关 Video Agent 服务的信息

资源

该服务提供动态资源，以便感知上下文：

• project://current - 当前项目详情
• project://{id}/timeline - 场景时间线
• project://{id}/costs - 成本明细
• platform://{name}/specs - 平台规格

提示词

交互式提示词可引导复杂工作流：

• video_creation_wizard - 包含平台优化的完整视频创作工作流
• script_to_scenes - 将脚本转换为场景规划，并提供时间安排建议
• list_video_agent_capabilities - 全面介绍服务的所有能力
• cinematic_photography_guide - 用于 AI 视觉内容的专业电影摄影技巧

配置

环境变量：

• FALAI_API_KEY - 您的 FAL AI API 密钥（必需）
• VIDEO_AGENT_STORAGE - 存储目录（默认值：./storage）
• DEFAULT_IMAGE_MODEL - 默认图像模型（默认值：imagen4）
• DEFAULT_VIDEO_MODEL - 默认视频模型（默认值：kling_2.1，选项：hailuo_02）

项目结构

video-agent-mcp/
├── src/mcp_server/
│   ├── config/      # Configuration and settings
│   ├── models/      # Data models
│   ├── tools/       # Tool implementations
│   ├── resources/   # Resource handlers
│   ├── prompts/     # Prompt templates
│   └── services/    # External service integrations
├── templates/       # Video templates
└── tests/          # Test suite

开发

设置开发环境

# Clone and enter the project
git clone <repository-url>
cd video-gen-mcp-monolithic

# Install with development dependencies
uv sync --dev

# Or install dev dependencies separately
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

添加新功能

1. 新工具：在 src/mcp_server/tools/ 中创建文件，并在 server.py 中注册
2. 新资源：在 resources/ 中创建处理程序，并使用装饰器注册
3. 新提示词：添加到 prompts/，用于引导式工作流

uv 故障排除

“No Python interpreter found”

# uv will use the Python version from .python-version (3.11)
# If you need a specific Python version:
uv python install 3.11
uv venv --python 3.11

macOS/Linux 上出现 “Permission denied”

# Ensure uv is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

“Module not found” 错误

# Ensure you're using uv run or have activated the venv
uv run python main.py
# OR
source .venv/bin/activate
python main.py

Claude Desktop 无法找到服务

1. 在配置中使用绝对路径
2. 确保在 env 部分设置了 FAL_API_KEY
3. 检查 Claude Desktop 日志中的错误
4. 先单独测试服务：uv run python main.py

YouTube 集成

有关 YouTube 上传功能，请参阅 YOUTUBE_SETUP.md，了解详细的 OAuth2 设置说明。

环境变量

在项目根目录中创建 .env 文件：

# Required
FALAI_API_KEY=your-fal-api-key

# Optional
VIDEO_AGENT_STORAGE=/path/to/storage  # Default: ./storage
DEFAULT_IMAGE_MODEL=imagen4           # Options: imagen4, flux_pro, flux_kontext
DEFAULT_VIDEO_MODEL=kling_2.1         # Options: kling_2.1, hailuo_02
GOOGLE_API_KEY=your-google-api-key    # For YouTube search features

许可证

[许可证信息]

贡献

[贡献指南]