Video Gen Mcp

An MCP server for AI-powered video creation using the FAL AI API.

A comprehensive Model Context Protocol (MCP) server for AI-powered video creation. This server provides tools, resources, and prompts to guide AI agents through complete video production workflows.

- Unified Interface: Single MCP server with all video creation capabilities
- Multi-Service Integration: Supports FAL AI services for image, video, audio, and speech generation
- Intelligent Workflows: Guided prompts that adapt to your project context
- Platform Optimization: Pre-configured settings for YouTube, TikTok, Instagram, and more
- Cost Tracking: Real-time cost estimation and tracking for all operations
- YouTube Integration: Direct upload to YouTube with OAuth2 authentication
- Modular Architecture: Clean separation of tools, resources, and prompts

- Python 3.11+
- FFmpeg installed on your system
- FAL AI API key
- uv (Python package manager)

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

# 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"

# 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

# 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

Add the following to your Claude Desktop configuration:

On macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonOn 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" } } } }

Important: Replace/absolute/path/to/video-gen-mcp-monolithicwith the actual path to your project directory.

Alternative: Using pyproject.toml script

Since we've defined a script entry point in pyproject.toml, you can also run:

# Install the package in development mode uv pip install -e . # Run using the script entry point uv run video-agent-mcp

Once configured in Claude Desktop, you can start creating videos:

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- Initialize a new video project with smart defaults based on platform
- add_scene- Add scenes to your timeline with description and duration
- list_projects- View all projects with their current status

- generate_image_from_text- Create images from text prompts with style modifiers
- generate_image_from_image- Transform existing images with AI-powered editing
- generate_video_from_image- Animate still images with AI-generated motion (supports Kling 2.1 and Hailuo 02 models)
- generate_music- Create background music from text descriptions
- generate_speech- Generate voiceovers with multiple voice options

Call generation tools sequentially for clear progress tracking and easier debugging.

- download_assets- Download generated assets from FAL or other sources
- add_audio_track- Add audio tracks to video with volume control
- assemble_video- Combine scenes into final video with quality presets

- analyze_script- Analyze scripts for video production insights
- suggest_scenes- Generate scene suggestions based on project script
- upload_image_file- Upload local image files to FAL for use in generation tools
- get_server_info- Get information about the Video Agent server

The server provides dynamic resources for context awareness:

- project://current- Current project details
- project://{id}/timeline- Scene timeline
- project://{id}/costs- Cost breakdown
- platform://{name}/specs- Platform specifications

Interactive prompts guide complex workflows:

- video_creation_wizard- Complete video creation workflow with platform optimization
- script_to_scenes- Convert scripts to scene plans with timing recommendations
- list_video_agent_capabilities- Comprehensive guide of all server capabilities
- cinematic_photography_guide- Professional cinematography techniques for AI visuals

- FALAI_API_KEY- Your FAL AI API key (required)
- VIDEO_AGENT_STORAGE- Storage directory (default: ./storage)
- DEFAULT_IMAGE_MODEL- Default image model (default: imagen4)
- DEFAULT_VIDEO_MODEL- Default video model (default: kling_2.1, options: 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 .

- New Tool: Create a file insrc/mcp_server/tools/and register inserver.py
- New Resource: Create handler inresources/and register with decorator
- New Prompt: Add toprompts/for guided workflows

# 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

"Permission denied" on macOS/Linux

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

# 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 can't find the server

For YouTube upload functionality, seeYOUTUBE_SETUP.mdfor detailed OAuth2 setup instructions.

# 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

Analyzes image and video content from URLs or local files using the Gemini 2.0 Flash model.