Video Agent MCP Server

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.

Features

• 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

Quick Start

Prerequisites

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

Installation with uv

1. Clone the repository:

git clone 
cd video-gen-mcp-monolithic

2. Install uv (if not already installed):

# 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. Set up the project with 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. Set up environment variables:

# Create a .env file in the project root
cat > .env 
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 .

Adding New Capabilities

1. New Tool: Create a file in `src/mcp_server/tools/` and register in `server.py`

2. New Resource: Create handler in `resources/` and register with decorator

3. New Prompt: Add to `prompts/` for guided workflows

Troubleshooting 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

"Permission denied" on macOS/Linux

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

"Module not found" errors

# 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

1. Use absolute paths in the configuration

2. Ensure FAL_API_KEY is set in the env section

3. Check Claude Desktop logs for errors

4. Test the server standalone first: `uv run python main.py`

YouTube Integration

For YouTube upload functionality, see YOUTUBE_SETUP.md for detailed OAuth2 setup instructions.

Environment Variables

Create a `.env` file in the project root:

# 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

License

[License information]

Contributing

[Contributing guidelines]